GET https://www.canath.io/.well-known/agent.json

Returns: all capabilities, fees, auth methods, x402 payment parameters,
settlement network, supported currencies, and discovery URLs —
one structured JSON file you can parse programmatically.

GET https://www.canath.io/api/nano/ping

Returns: {
  network: "eip155:137",   // Polygon mainnet
  asset:   "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",  // Circle USDC
  payTo:   "<Canath fee wallet>",
  endpoints: { ping, search, lookup, quote }   // with prices
}

// Use @x402/fetch — handles 402, signs EIP-3009, retries automatically
import { wrapFetch } from "@x402/fetch";
const x402fetch = wrapFetch(wallet);

const res = await x402fetch(
  "https://www.canath.io/api/nano/search?q=running+shoes&website=nike.com"
);
// $0.001 USDC deducted per call · no account needed · Polygon only

GET https://www.canath.io/mcp

Returns: server name, version, all tool names, docs link, and agent.json URL.

POST https://www.canath.io/mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": { "name": "my-agent", "version": "1.0" }
  }
}

// Register + get wallet in one call
POST https://www.canath.io/mcp
{ "jsonrpc":"2.0","id":2,"method":"tools/call","params":{
    "name":"register_agent",
    "arguments":{ "email":"agent@example.com","password":"secure123" }
}}

// Send USDC
{ "jsonrpc":"2.0","id":3,"method":"tools/call","params":{
    "name":"send_payment",
    "arguments":{ "api_key":"pa_live_...","recipient_handle":"PA-ABCD1234","amount":10,"currency":"USDC" }
}}

// Search products
{ "jsonrpc":"2.0","id":4,"method":"tools/call","params":{
    "name":"search_products",
    "arguments":{ "api_key":"pa_live_...","query":"running shoes","website":"nike.com" }
}}

Canath A2A Protocol

www.canath.io/a2a.html · Agent-to-Agent payments & shopping · Circle only: USDCEURCShop

A2A lets one AI agent send money to another AI agent — or to any Canath user — or shop from any merchant, fully autonomously. Each agent is backed by a human-owned Canath account. The human sets it up once; the agent handles payments and shopping from then on. This is the infrastructure layer for the agentic economy: agents with their own phone numbers and email addresses can pay each other and buy things — no browser, no card required.

Agent Identity Channels

AI agents will have phone numbers and email addresses just like people. Canath treats each of these as a first-class payment identity:

Phone number as recipient identity

Any Canath user (or agent) who has linked their phone number can receive money by phone number:

send 50 usdc to +17125551234
send 100 eurc to +16055550100

Email-triggered payment (for agents with email)

An AI agent with an email address can initiate a payment by emailing pay@canath.io. The FROM address is their Canath identity — no password or API key needed in the email body:

To: pay@canath.io
From: agent@yourdomain.com
Subject: payment

send 50 usdc to recipient@example.com
send 100 eurc to +17125551234

Canath replies with a confirmation including the transfer ID and fee breakdown. Webhook URL for email providers: https://www.canath.io/api/email/inbound

Agent Self-Registration — One API Call, No Browser Needed

An AI agent can create its own Canath account and Circle USDC/EURC wallet with a single HTTP call — no human, no browser, no verification email to click. The wallet is provisioned and the deposit address returned immediately in the same response.

POST https://www.canath.io/api/agent/register
Content-Type: application/json

{
  "email":     "agent@example.com",
  "password":  "minimum-8-chars",
  "agentName": "MyAgent v1"          // optional — labels the API key
}

// Response (201 Created — new account):
{
  "apiKey":         "pa_live_...",      // store this — shown only once
  "agentHandle":    "PA-XXXXXXXX",      // agent's Canath payment address
  "circleWalletId": "...",              // Circle wallet ID (USDC + EURC)
  "depositAddress": "0x...",            // Polygon address — fund here
  "network":        "Polygon (MATIC)",
  "isNewAccount":   true,
  "message":        "Account and Circle wallet created. Fund depositAddress with USDC or EURC on Polygon to start transacting."
}

// Returning agent (re-auth, issues a fresh key):
POST same endpoint → { "apiKey": "pa_live_...", "isNewAccount": false, ... }

What the agent gets in one call:
✅ Canath identity (handle + API key)
✅ Circle USDC wallet provisioned and ready
✅ Polygon deposit address to receive funds immediately
✅ Full access to send, shop, bridge, swap via the pa_live_ key

After registration — fund the wallet

// Option A — on-chain deposit (send USDC to depositAddress on Polygon)
// Option B — Circle Mint funding link (agent generates this for its user)
POST https://www.canath.io/api/circle/buy-session
Authorization: Bearer pa_live_...
{ "amount": 100, "currency": "USDC" }
→ { "url": "...", "expiresAt": "..." }   // share this link with the human funder

SEND MONEY — USDC & EURC (choices 1 & 2)

Simplified transfer endpoint: POST /api/agent/transfer — no lookup step required. Pass handle, email, or phone number directly in the to field. Canath resolves the recipient automatically.

Step 1 — Optional: preview fee before sending

GET https://www.canath.io/api/agent/transfer/quote?to=PA-B5C6D7E8&amount=25.00
// or: ?to=recipient@example.com&amount=25.00
// Returns: { "fee": 0.37, "feeRate": 0.0149, "recipientAmount": 24.63, "currency": "USDC" }

Step 2 — Confirm before executing (always ask the user first)

Step 3 — Execute on YES (USDC or EURC)

POST https://www.canath.io/api/agent/transfer
Authorization: Bearer <sender's pa_live_ API key>
Content-Type: application/json

{ "to": "PA-B5C6D7E8", "amount": 25.00, "currency": "USDC" }
// "to" accepts: Canath handle (PA-XXXXXXXX), email address, or phone number
// Use "EURC" for Euro Coin

// Response:
{ "transferId": "...", "status": "complete", "fee": 0.37, "recipientAmount": 24.63 }

Step 4 — Report back to the user

SHOPPING — Buy from any merchant (choice 3)

Pay with USDC or EURC from your Circle wallet. 1.49% fee per order. No card, no fiat.

Step A — Search products

POST https://www.canath.io/api/shopping/search
Authorization: Bearer <pa_live_ API key>
Content-Type: application/json

{ "website": "nike.com", "query": "running shoes" }

Returns:
{
  "products": [
    { "title": "Air Zoom Pegasus 41", "brand": "Nike", "price": "$130.00", "priceNum": 130.00, "url": "..." },
    ...
  ],
  "previewUrl": "https://www.canath.io/api/product-preview/TOKEN"
}

Share previewUrl so user can see product photos. Present up to 4 products numbered.

Step B — Confirm and buy

POST https://www.canath.io/api/shopping/buy
Authorization: Bearer <pa_live_ API key>
Content-Type: application/json

{
  "website": "nike.com",
  "productTitle": "Air Zoom Pegasus 41",
  "productBrand": "Nike",
  "amount": 130.00,
  "paymentMethod": "usdc",
  "shippingAddress": "123 Main St, Austin TX 78701, USA"
}

Returns on success:
{
  "success": true,
  "orderId": "...",
  "transferId": "...",
  "amount": 130.00,
  "fee": 1.94,
  "total": 131.94,
  "currency": "USDC",
  "status": "completed"
}

Error handling:
shipping_address_required (400) → ask user for address, retry with shippingAddress.
merchant_not_gated (403) → say: "[site] hasn't enabled Canath orders yet. Try another merchant."
Fiat/card requested → say: "Shopping on Canath is Circle only — USDC or EURC."

Step C — Report back

NANO API — x402 Pay-Per-Use (choice 4)

Canath exposes pay-per-use API endpoints using the x402 HTTP payment protocol (Circle Nano Payments, live April 2026). Any AI agent with USDC on Polygon can call these with no pa_live_ API key — they pay a tiny USDC fee per request via an EIP-3009 signed transfer, fully autonomously.

Use nano endpoints when you need product data, user lookups, or fee quotes and don't have (or don't want to use) a Canath API key. Payment happens inside the HTTP request — no account, no subscription.

How x402 works (two HTTP calls)

// CALL 1 — no payment header
GET https://www.canath.io/api/nano/search?q=coffee&website=amazon.com

// Server responds:
HTTP 402 Payment Required
{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:137",
    "maxAmountRequired": "1000",
    "payTo": "<Canath fee wallet>",
    "asset": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
    "extra": { "name": "USDC", "version": "2" }
  }]
}

// CALL 2 — sign EIP-3009 off-chain, attach as header
GET https://www.canath.io/api/nano/search?q=coffee&website=amazon.com
X-PAYMENT: <base64-encoded signed payload>

// Server responds:
HTTP 200 { "products": [...] }

// Use @x402/fetch or @x402/axios to automate steps 1–2

Nano endpoints

GET /api/nano/ping
  Cost: FREE — service discovery, no payment header needed
  Returns: { network, asset, payTo, endpoints }

GET /api/nano/search?q=<query>&website=<domain>
  Cost: $0.001 USDC (1,000 token units on Polygon)
  Returns: { products: [{ title, price, brand, rating, reviews, url }] }

GET /api/nano/lookup?email=<email>
GET /api/nano/lookup?handle=<handle>
  Cost: $0.0001 USDC (100 token units)
  Returns: { found, handle, displayName, canReceive }

GET /api/nano/quote?amount=<num>&currency=usdc|eurc&action=transfer|swap
  Cost: $0.0001 USDC (100 token units)
  Returns: { fee, feeRate, total, received, settlementTime }

Payment parameters (read from the 402 response body)

network:  eip155:137                                          (Polygon mainnet)
asset:    0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359          (Circle USDC, 6 decimals)
scheme:   exact
version:  2  (EIP-712 domain version for Circle USDC — required for EIP-3009 signing)

Example with @x402/fetch (Coinbase AgentKit)

import { wrapFetchWithPayment } from "@x402/fetch";
import { CdpAgentkit } from "@coinbase/cdp-agentkit-core";

const agentkit = await CdpAgentkit.configureWithWallet({ ... });
const fetchWithPayment = wrapFetchWithPayment(fetch, agentkit);

// Product search — pays $0.001 USDC automatically
const res = await fetchWithPayment(
  "https://www.canath.io/api/nano/search?q=running+shoes&website=nike.com"
);
const { products } = await res.json();

// User lookup — pays $0.0001 USDC automatically
const res2 = await fetchWithPayment(
  "https://www.canath.io/api/nano/lookup?email=recipient@example.com"
);
const { found, handle } = await res2.json();

Webhooks — Real-time push notifications

Register HTTPS endpoints that Canath pushes to automatically after every Circle transfer. Ideal for autonomous agents that need to react when they receive money — no polling loop needed.

Events fired automatically after every POST /api/circle/transfer:

• payment.sent — fires to the sender (transfer ID, amount, fee, recipient)
• payment.received — fires to the recipient (transfer ID, amount, sender)

Register a webhook

POST https://www.canath.io/api/webhooks
Authorization: Bearer <pa_live_ API key>
Content-Type: application/json

{
  "url":    "https://your-agent.com/hooks/canath",
  "events": ["payment.received"],        // or ["payment.sent"], or both
  "secret": "optional-hmac-secret"       // enables X-Canath-Signature on each delivery
}

Returns: { "id": "...", "url": "...", "events": [...] }

Webhook endpoints

GET    /api/webhooks            — list all webhooks (Bearer)
POST   /api/webhooks            — register a new webhook (Bearer)
DELETE /api/webhooks/:id        — remove a webhook (Bearer)
GET    /api/webhooks/deliveries — delivery log: status, HTTP code, retries (Bearer)

Deliveries are retried up to 3× with exponential backoff. Payloads are HMAC-SHA256 signed (X-Canath-Signature) when a secret is set. Delivery happens after the transfer response — never blocks the payment.

Streaming Search — SSE

Stream product search results progressively via Server-Sent Events. Results appear as the AI finds them — no need to wait for the full response before rendering.

GET https://www.canath.io/api/shopping/search/stream?q=running+shoes&website=nike.com
Authorization: Bearer <pa_live_ API key>
Accept: text/event-stream

// Events:
event: result  data: { "title": "...", "price": "$130.00", "priceNum": 130, ... }
event: result  data: { ... }
event: done    data: {}
// event: error  data: { "reason": "..." }  — on failure

Agent Invoicing — Request payment from another agent

One agent issues a USDC or EURC invoice to another. The receiving agent pays with a single API call, which executes a Circle transfer and marks the invoice paid — atomic and traceable.

Create an invoice

POST https://www.canath.io/api/invoices
Authorization: Bearer <issuer's pa_live_ API key>
Content-Type: application/json

{
  "toHandle":    "PA-XXXXXXXX",              // or "toEmail": "agent@example.com"
  "amount":      50.00,
  "currency":    "USDC",                     // or "EURC"
  "description": "Data services — May 2026",
  "dueAt":       "2026-05-31T23:59:59Z"     // optional
}

Returns: { "id": "inv_...", "status": "pending", "amount": 50, "currency": "USDC", ... }

Pay an invoice

POST https://www.canath.io/api/invoices/inv_.../pay
Authorization: Bearer <payer's pa_live_ API key>

Returns: { "status": "paid", "transferId": "...", "paidAt": "..." }

Invoice lifecycle endpoints

POST /api/invoices            — create invoice (Bearer)
GET  /api/invoices            — list sent + received invoices (Bearer)
GET  /api/invoices/:id        — invoice detail (Bearer)
POST /api/invoices/:id/pay    — pay invoice → executes Circle transfer (Bearer)
POST /api/invoices/:id/cancel — cancel sent invoice (pending only) (Bearer)

Invoice statuses: pending → paid or cancelled.
Paying an invoice calls POST /api/circle/transfer internally and records the transfer_id on the invoice. payment.sent / payment.received webhooks fire as normal.

Rate-Limit Tiers

All pa_live_ API requests are rate-limited per account. Upgrade to pro instantly — no support ticket needed.

POST https://www.canath.io/api/account/tier
Authorization: Bearer <pa_live_ API key>
Content-Type: application/json

{ "tier": "pro" }

Returns: { "tier": "pro", "rateLimit": "300 req/min", "message": "Account upgraded to pro tier. 300 req/min rate limit now active." }

Takes effect immediately on all subsequent requests.

Account Setup (human does this once)

Fee Summary

Quick Reference

Machine Discovery

If you are an autonomous agent indexing this service, fetch the structured capability manifest:

GET https://www.canath.io/.well-known/agent.json

Returns: all capabilities, fees, auth methods, x402 payment parameters,
settlement network, and discovery URLs — in a single parseable JSON file.
No payment required.

Start with the nano ping to get live payment parameters:

GET https://www.canath.io/api/nano/ping
→ { network, asset, payTo, endpoints: { prices } }

Agent service descriptor: www.canath.io/.well-known/agent.json · Full instructions: www.canath.io/ai.html · Agent docs: www.canath.io/agent · Nano discovery: www.canath.io/api/nano/ping · Canath: www.canath.io