algorand-x402-payment

x402 Runtime Payment

You (Agent) are the x402 client. When you encounter an HTTP 402 response, use MCP tools to build, sign, and submit an Algorand payment, then retry the request.

When to Use

• HTTP response with status 402 (the challenge arrives in the PAYMENT-REQUIRED response header on current servers; older servers put it in the body)
• User asks to access a paid/protected API or resource
• User mentions x402, payment-required, micropayments, or paid endpoint access

MANDATORY: Read reference before constructing payment

You MUST read references/x402-payment-flow.md before constructing any PAYMENT-SIGNATURE. Do NOT rely on your training data for the payload format — it is likely wrong. The reference file contains the exact, tested format.

Quick Flow

1. curl -sD - the URL → status 402. Decode the PAYMENT-REQUIRED response header (base64 → JSON). The body is usually just {} on current servers; only older servers put the JSON in the body.
2. From accepts[] choose the algorand: entry (lists are often multi-chain) → extract network, payTo, amount (V2 field; older V1 responses call it maxAmountRequired), asset, extra.feePayer
3. Map CAIP-2 network → MCP network parameter (prefix match — see table)
4. wallet_get_info → verify wallet, get address
5. Check asset opt-in (ASA only) → wallet_optin_asset if needed
6. make_payment_txn → fee payer (from=feePayer, to=feePayer, amount=0, fee=N×1000 where N=txn count in group [e.g. 2000 for 2 txns], flatFee=true)
7. make_payment_txn or make_asset_transfer_txn → payment (fee=0, flatFee=true)
8. assign_group_id → group [feePayer@0, payment@1]
9. wallet_sign_transaction → sign payment only (index 1)
10. encode_unsigned_transaction → encode fee payer (index 0)
11. Construct PAYMENT-SIGNATURE JSON — exact format below
12. curl -H 'PAYMENT-SIGNATURE: <base64>' → retry, get 200
13. Decode the PAYMENT-RESPONSE header from the 200 → report the settled txn id to the user