GET https://www.airpay.sh/.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.airpay.sh/api/nano/ping

Returns: {
  network: "eip155:137",   // Polygon mainnet
  asset:   "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",  // Circle USDC
  payTo:   "<AirPay 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.airpay.sh/api/nano/search?q=running+shoes&website=nike.com"
);
// $0.001 USDC deducted per call · no account needed · Polygon only

GET https://www.airpay.sh/mcp

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

POST https://www.airpay.sh/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.airpay.sh/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" }
}}

// Get fee quote
{ "jsonrpc":"2.0","id":4,"method":"tools/call","params":{
    "name":"get_quote",
    "arguments":{ "to":"PA-XXXXXXXX","amount":50,"currency":"USDC" }
}}

AirPay A2A Protocol

www.airpay.sh/a2a.html · Agent-to-Agent payments · Circle only: USDCEURC

A2A lets one AI agent send money to another AI agent — or to any AirPay user — fully autonomously. Each agent is backed by a human-owned AirPay account. The human sets it up once; the agent handles payments from then on. This is the infrastructure layer for the agentic economy: agents can pay each other — no browser, no card required.

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

An AI agent can create its own AirPay 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.airpay.sh/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 AirPay 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:
✅ AirPay identity (handle + API key)
✅ Circle USDC wallet provisioned and ready
✅ Polygon deposit address to receive funds immediately
✅ Full access to send, bridge, and 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.airpay.sh/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 or email directly in the to field. AirPay resolves the recipient automatically.

Step 1 — Optional: preview fee before sending

GET https://www.airpay.sh/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.airpay.sh/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: AirPay handle (PA-XXXXXXXX) or email address
// Use "EURC" for Euro Coin

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

Step 4 — Report back to the user

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

AirPay 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 AirPay 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.airpay.sh/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": "<AirPay fee wallet>",
    "asset": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
    "extra": { "name": "USDC", "version": "2" }
  }]
}

// CALL 2 — sign EIP-3009 off-chain, attach as header
GET https://www.airpay.sh/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.airpay.sh/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.airpay.sh/api/nano/lookup?email=recipient@example.com"
);
const { found, handle } = await res2.json();

Webhooks — Real-time push notifications

Register HTTPS endpoints that AirPay 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.airpay.sh/api/webhooks
Authorization: Bearer <pa_live_ API key>
Content-Type: application/json

{
  "url":    "https://your-agent.com/hooks/airpay",
  "events": ["payment.received"],        // or ["payment.sent"], or both
  "secret": "optional-hmac-secret"       // enables X-AirPay-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-AirPay-Signature) when a secret is set. Delivery happens after the transfer response — never blocks the payment.

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.airpay.sh/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.airpay.sh/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.airpay.sh/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.airpay.sh/.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.airpay.sh/api/nano/ping
→ { network, asset, payTo, endpoints: { prices } }

Agent service descriptor: www.airpay.sh/.well-known/agent.json · Full instructions: www.airpay.sh/ai.html · Agent docs: www.airpay.sh/agent · Nano discovery: www.airpay.sh/api/nano/ping · AirPay: www.airpay.sh