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: micro-USDC integer string (e.g. 50000 for 0.05 USDC). Discovery also exposes priceUsdc.

Per-route pricing (defaults)

Confirm against live discovery before integrating. Documented defaults:

GET /v1/alpha/opportunities — 0.05 USDC
GET /v1/alpha/markets/{marketAppId} — 0.05 USDC
GET /v1/alpha/quotes — 0.06 USDC
GET /v1/alpha/scan — 0.25 USDC
POST /v1/alpha/execution/quotes — 0.10 USDC

Free: /health, /discovery, /openapi.json, /v1/alpha/execution/shapes. See the endpoint catalog for current values from discovery metadata.

Unsigned execution quotes

Call free GET /v1/alpha/execution/shapes to learn supported builders.
Preflight paid POST /v1/alpha/execution/quotes, satisfy its x402 requirement, and retry with PAYMENT-SIGNATURE.
Sign only the returned userSignIndexes / unsignedTxnsBase64, then submit through your own Algod client.

Amarok never receives wallet keys and never submits orders. meta.executionSubmitted is always false.

MCP server (agent tools)

Agents can connect to the remote Amarok 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://amarok-mcp.compx.io/mcp
No server-side wallet or mnemonic storage in MCP
Tools include amarok_list_opportunities, amarok_get_execution_quote, and free discovery helpers

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

{
  "mcpServers": {
    "amarok": {
      "url": "https://amarok-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://amarok-api.compx.io/v1/alpha/opportunities