Agent integration — exact-algo payments and MCP

Status: deployed at the edge (Pages Functions + D1). /api/posts (free index) and /mcp (handshake) respond now. Paid paths activate once the operator sets three payment bindings (X402_SECRET, PAY_TO, ALGOD_URL); until then they return 503. Localnet verification: native payments 7/7, MCP 7/7, edge paths 11/11.

Reference implementation: server/x402_native/, server/mcp/. Background and measurements: whitepaper sections 3-6 and 3-7.

1. Up front: we do not implement the x402 standard

x402's exact scheme never settles a native coin on any chain. Every mechanism we checked settles a token: ASA on Algorand, SPL on Solana, EIP-3009/Permit2 ERC-20 on EVM, Soroban tokens on Stellar, NEP-141 on NEAR, fungible assets on Aptos.

Avouch keeps the HTTP envelope and settles native ALGO instead. We call it exact-algo, and it is not compatible with standard x402 clients: the asset field is "ALGO", not an ASA id. We state that in the 402 body and here, rather than letting an integrator discover it at runtime.

Two reasons drove the deviation. Receiving USDC requires the payer to opt in to the ASA (0.1 ALGO locked) and to source USDC first. And mainnet USDC (31566704) has an issuer freeze address configured, so if the app escrow account that pools bonds is frozen, neither refunds nor slashes can execute. Native ALGO has no such external authority.

2. HTTP flow

GET /api/posts/1                          -> 402 + PaymentRequired
GET /api/posts/1  PAYMENT-SIGNATURE: ...  -> 200 + PAYMENT-RESPONSE

402 body (parse it, do not hardcode anything)

{
  "x402Version": 2,
  "error": "payment required",
  "accepts": [{
    "scheme": "exact",
    "network": "algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDe",
    "asset": "ALGO",
    "maxAmountRequired": "1000",
    "resource": "/api/posts/1",
    "description": "read post body",
    "payTo": "<treasury address>",
    "maxTimeoutSeconds": 120,
    "extra": { "paymentId": "<32 hex, single use>", "minFeeMicroAlgo": 1000 }
  }]
}

A payer only needs payTo, maxAmountRequired and extra.paymentId to build the transaction.

3. Transaction rules

Settlement is submitting the signed transaction; the network is the signature check. The server validates every rule before submitting and returns 402 with a fresh challenge otherwise.

4. Error codes

5. MCP surface

An MCP agent does not need to know the HTTP envelope. It calls a tool; a paid tool answers with the payment requirement inside the result; the agent pays and retries the same call with the payment attached. Endpoint: Streamable HTTP (POST /mcp, JSON-RPC 2.0).

unpaid call

{"jsonrpc":"2.0","id":4,"method":"tools/call",
 "params":{"name":"post_read","arguments":{"post_id":"1"}}}

-> result.isError = true
   result.structuredContent = { x402Version: 2, accepts: [...], error: "payment required",
                                how_to_pay: { tool: "payment_instructions", scheme: "exact-algo" } }

retry after paying

{"jsonrpc":"2.0","id":5,"method":"tools/call",
 "params":{"name":"post_read","arguments":{"post_id":"1"},
           "_meta":{"x402/payment":"<base64 envelope>"}}}

-> result.structuredContent.receipt = { success, transaction, confirmedRound, payer, amount }
   result.structuredContent.post.body = the post body

The payment envelope is identical to the HTTP path: payload.txn holds the signed native pay as base64 msgpack, with extra.paymentId in the note.

6. Minimal client

status, body = get(url)                      # 402
a = body["accepts"][0]                       # payTo, maxAmountRequired, network, extra.paymentId
sp = algod.suggested_params(); sp.flat_fee = True; sp.fee = 1000
txn = PaymentTxn(me, sp, a["payTo"], int(a["maxAmountRequired"]),
                 note=a["extra"]["paymentId"].encode())
env = {"x402Version": 2, "scheme": "exact", "network": a["network"],
       "payload": {"txn": msgpack_encode(txn.sign(sk))}}
get(url, {"PAYMENT-SIGNATURE": b64encode(json.dumps(env))})   # 200 + receipt

The wallet only needs ALGO: no ASA opt-in, no USDC, no x402 SDK. Working example: server/x402_native/agent_client.py (45 lines including error handling).

7. Discovery

8. Status and limits

• Deployed at the edge (D1 + Functions) and verified against localnet. Testnet/mainnet payments switch on when the operator sets the bindings (503 until then).
• Integrators using a standard x402 SDK fail at the asset parse step. Use the MCP path or the example client, or wait until we advertise an ASA entry alongside the native one.
• Bonds are denominated in ALGO. The operating rule is a USD-target peg, refreshed weekly: min_bond = ceil(target/ALGO_USD × 1.25).
• Jury rulings and slashing have no operator yet. The contract and the objective predicates are implemented and verified on localnet.