x402 payment flow

Payment enforcement happens at the Caddy gateway. The API publishes payment requirements through discovery and OpenAPI; the gateway verifies and settles via the facilitator.

1. Preflight Call a paid route without PAYMENT-SIGNATURE. Gateway returns 402 with PAYMENT-REQUIRED.

2. Sign Client wallet builds and signs the USDC transfer payload expected by the facilitator.

3. Retry Resend the request with PAYMENT-SIGNATURE. Caddy verifies and settles via facilitator.

4. Success Paid route returns 200 and may include PAYMENT-RESPONSE settlement metadata.

Required headers

PAYMENT-REQUIRED — returned on initial paid preflight (402).
PAYMENT-SIGNATURE — client retry header containing signed payment payload.
PAYMENT-RESPONSE — optional success header with settlement receipt metadata.

Typical accept policy fields

scheme: usually exact
network: e.g. algorand-mainnet
asset: USDC ASA id on Algorand mainnet
payTo: receiver address configured for the gateway
maxAmountRequired: USDC-denominated amount for the route (e.g. 0.01).

Per-route pricing

Most paid routes default to 0.01 USDC. Wallet-personalized opportunities at /opportunities/personalized cost 0.05 USDC, while /positions?address= costs exactly 0.005 USDC (5000 micro-USDC). Eligibility POST /eligibility costs 0.01 USDC (10000 micro-USDC). Intent compiler POST /plans costs 0.25 USDC (250000 micro-USDC). Claim desk /positions/claimable?address= costs exactly 0.001 USDC (1000 micro-USDC). Batch execution quotes at POST /execution/quotes cost 0.1 USDC flat per request (not per quote item). Haystack quote and prerequisite opt-in generation are free; only POST /swaps/transactions costs 0.005 USDC. Discovery x402 metadata exposes both amountUsdc and amountMicro; Caddy PAYMENT-REQUIRED uses micro-USDC. See the endpoint catalog for current values from discovery metadata.

Walletless Haystack swaps

Request a free POST /swaps/quote using integer asset base units.
Call free POST /swaps/optin. If it returns transactions, sign and submit them locally, wait for confirmation, then request a fresh quote.
Preflight paid POST /swaps/transactions, satisfy its 0.005 USDC x402 requirement, and retry with PAYMENT-SIGNATURE.
Sign only the returned userSignIndexes, preserve Haystack pre-signed members and atomic-group order, then submit the complete group through your own Algod client.

1) Free quote

curl -i https://canix402-api.compx.io/swaps/quote \
  -H 'content-type: application/json' \
  -d '{
    "address": "YOUR_ALGORAND_ADDRESS",
    "fromAssetId": 0,
    "toAssetId": 31566704,
    "amount": "1000000",
    "type": "fixed-input"
  }'

2) Free opt-in

curl -i https://canix402-api.compx.io/swaps/optin \
  -H 'content-type: application/json' \
  -d '{
    "address": "YOUR_ALGORAND_ADDRESS",
    "quote": { /* full data object from /swaps/quote */ }
  }'

3) Paid transactions — preflight then retry

curl -i https://canix402-api.compx.io/swaps/transactions \
  -H 'content-type: application/json' \
  -d '{
    "address": "YOUR_ALGORAND_ADDRESS",
    "quote": { /* fresh quote data object */ },
    "slippage": 0.005
  }'

curl -i https://canix402-api.compx.io/swaps/transactions \
  -H 'content-type: application/json' \
  -H 'PAYMENT-SIGNATURE: <base64-json-payload>' \
  -d '{
    "address": "YOUR_ALGORAND_ADDRESS",
    "quote": { /* fresh quote data object */ },
    "slippage": 0.005
  }'

Quotes are short-lived. Canix402 never receives wallet keys and never submits opt-ins or swaps. The x402 access charge is separate from Haystack's SDK-default 10 bps output fee (including its referral split), DEX fees, route price impact, and Algorand network fees. Sample payloads: examples.

MCP server (agent tools)

Agents can connect to the remote canix402 MCP endpoint instead of calling HTTP endpoints directly. The MCP layer is walletless: paid tools return payment requirements first, then accept a caller-supplied paymentSignature on retry.

Transport: streamable-http
Remote URL: https://canix402-mcp.compx.io/mcp
No server-side wallet or mnemonic storage in MCP
Tools include canix_list_opportunities, canix_list_execution_shapes, canix_get_positions, canix_get_plan, canix_get_execution_quote, and free discovery helpers

Full setup, tool list, and paid-tool flow: MCP documentation.

{
  "mcpServers": {
    "canix402": {
      "url": "https://canix402-mcp.compx.io/mcp"
    }
  }
}

Common failure modes

402 without signature — expected preflight behavior.
Malformed signature — gateway/facilitator rejects before upstream call.
Expired proof — retry with a fresh signed payload.
Policy mismatch — network, asset id, payTo, or amount do not match discovery/Caddy policy.

curl -i https://canix402-api.compx.io/opportunities