axonpayDocs

Start hereLive

How it works

One request, one 402, one signature, one Solana transaction. This is the full path of a paid call and who does what along it.

On this page+

The round trip

  1. 1
    The agent sends an ordinary request, for example GET /api/forecast?city=Lisbon.
  2. 2
    The seller’s Axon Gate answers 402 Payment Required with a PAYMENT-REQUIRED header: base64 JSON listing the offers it accepts. Each offer names the scheme (exact), the network, the token mint, the amount in atomic units, the payTo address and the facilitator’s fee-payer address.
  3. 3
    The agent’s client picks an offer it is allowed to pay (this is where the mandate is checked), builds a Solana transaction that moves exactly that amount with SPL TransferChecked, and signs it as owner of the tokens. The fee-payer signature is left empty.
  4. 4
    The agent repeats the same request with the signed transaction in a PAYMENT-SIGNATURE header.
  5. 5
    The gate asks the facilitator to verify the transaction (right mint, right amount, right recipient, nothing extra), runs the handler, then asks it to settle: the facilitator adds its fee-payer signature and submits.
  6. 6
    The response comes back with the body and a PAYMENT-RESPONSE header holding the transaction signature. That signature is the receipt.
the exchange on the wire
GET /api/forecast?city=Lisbon HTTP/1.1
Host: seller.example.com

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6Mi…   (base64 JSON: the offers)

GET /api/forecast?city=Lisbon HTTP/1.1
Host: seller.example.com
PAYMENT-SIGNATURE: eyJ4NDAyVmVyc2lvbiI6Mi…   (base64 JSON: the signed transfer)

HTTP/1.1 200 OK
Content-Type: application/json
PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVl…   (base64 JSON: the receipt)

{"city":"Lisbon","summary":"Clear, 21°C, wind 9 km/h"}

Who does what

RoleRunsKeys it holds
SellerAxon Gate (x402 middleware) inside its own serverNone. It only publishes a payTo address.
Agent (buyer)An x402 client wrapped around fetchIts own agent keypair, funded with a small balance
FacilitatorThe verify and settle endpoints (Axonpay runs one; others exist)A fee-payer keypair. It pays the SOL fee but cannot redirect the transfer.
AxonpayIts facilitator, the receipts ledger, dApp, Agent Shop, 402 Inspector, Leash, MCP serverOnly its facilitator's fee payer. None of yours: agent keys are encrypted in your browser.

Why Solana

  • Fast enough to sit inside a request. Slots are about 400 ms and a transfer is usually confirmed in one to two seconds, so the paid response arrives in roughly the time of a slow API call.
  • Cheap enough for sub-cent prices. The base fee is 5,000 lamports per signature. An x402 payment carries two, so the network fee is 0.00001 SOL, and the facilitator pays it.
  • Native dollars. USDC is a first-class SPL token with deep liquidity; nothing has to be bridged.
  • Room for several transfers in one transaction. That is what planned composite calls and revenue splits build on.
  • Public, permanent signatures. Receipts that anyone can check without trusting Axonpay.

Where Axonpay fits

x402 is an open protocol, and its reference packages already speak Solana. Axonpay does not fork it. Axon Gate and the agent client are thin layers over the official @x402/* packages, so whatever you build here interoperates with every other x402 client and server.

What Axonpay adds sits around the protocol: a free facilitator that settles Solana and records every settle, a shop to be found in, an inspector to read a price before paying, wallets and mandates that keep agents in bounds, and an Axon Score computed from receipts.