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. For a session SKU, present AMAROK-SESSION on later research GETs instead of a new signature.

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. 5000 for 0.005 USDC). Discovery also exposes priceUsdc.

Per-route pricing (defaults)

Confirm against live discovery before integrating. Documented defaults:

GET /v1/alpha/opportunities — 0.005 USDC
GET /v1/alpha/markets/{marketAppId} — 0.005 USDC
GET /v1/alpha/quotes — 0.006 USDC
GET /v1/alpha/scan — 0.025 USDC
GET /v1/alpha/portfolio/{address} — 0.005 USDC
POST /v1/alpha/advisor — 0.008 USDC
GET /v1/alpha/bundle — 0.02 USDC (opportunities + quotes + N markets)
POST /v1/alpha/session — 0.03 USDC (1h research GETs via AMAROK-SESSION)
POST /v1/alpha/watchlist / GET /v1/alpha/watchlist — 0.008 USDC (register ids; poll deltas only)
POST /v1/alpha/execution/quotes — 0.01 USDC
Scan-only GET /v1/polymarket/* and GET /v1/kalshi/* share the matching Alpha SKUs (scan 0.025, rewards/spreads/parity/opportunities/market as above). No quotes or bundle SKUs on those families.

Per-request 402 is the default. Bundle and session are additive: pay GET /v1/alpha/bundle once for a composite payload, or POST /v1/alpha/session and present AMAROK-SESSION on covered research GETs. Do not replay PAYMENT-SIGNATURE.

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

Cursor and Claude Desktop configs: quickstart. Full tool list: 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