Quickstart

Use the Caddy gateway URL as your base URL. Discovery, OpenAPI, GET /execution/shapes, and POST /swaps/quote are free; paid data, quote, and swap-transaction routes require x402 USDC payment.

Option A: Use MCP (recommended for agent hosts)

Connect your MCP client to https://canix402-mcp.compx.io/mcp (Streamable HTTP). Free tools wrap discovery and health; paid tools return payment requirements, then accept paymentSignature on retry. No mnemonic on the MCP server.

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

See MCP documentation for the full tool list and paid-tool flow.

Option B: Direct HTTP

Read discovery and OpenAPI, then call paid routes with x402 headers as below.

1. Read discovery

Fetch the machine-readable endpoint catalog and payment policy.

curl -s https://canix402-api.compx.io/discovery | jq

2. Read OpenAPI

Use OpenAPI for detailed schemas, query params, and x402 metadata.

curl -s https://canix402-api.compx.io/openapi.json | jq '.paths | keys'

3. Probe free routes

Health, metadata, GET /execution/shapes, and POST /swaps/quote should return 200 without payment headers.

curl -i https://canix402-api.compx.io/health
curl -i https://canix402-api.compx.io/metadata
curl -i https://canix402-api.compx.io/execution/shapes
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"}'

4. Call a paid route

First call returns 402 with PAYMENT-REQUIRED. Retry with a signed payload. Same pattern for opportunities, positions, execution quotes, and Haystack POST /swaps/transactions.

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.

# Opportunities
curl -i https://canix402-api.compx.io/opportunities
curl -i https://canix402-api.compx.io/opportunities \
  -H 'PAYMENT-SIGNATURE: <base64-json-payload>'

# Positions
curl -i 'https://canix402-api.compx.io/positions?address=YOUR_ALGORAND_ADDRESS'
curl -i 'https://canix402-api.compx.io/positions?address=YOUR_ALGORAND_ADDRESS' \
  -H 'PAYMENT-SIGNATURE: <base64-json-payload>'

# Execution quotes (see /examples for full bodies)
curl -i https://canix402-api.compx.io/execution/quotes \
  -H 'content-type: application/json' \
  -d '{"quotes":[{"shapeKey":"mainnet:tinyman:v2:addLiquidity:flexible","input":{"userAddress":"YOUR_ALGORAND_ADDRESS","assetAId":0,"assetAAmount":"1000000","assetBId":31566704,"assetBAmount":"1000000","maxSlippageBps":50}}]}'

# Haystack swap transactions (after free quote + opt-in)
curl -i https://canix402-api.compx.io/swaps/transactions \
  -H 'content-type: application/json' \
  -d '{"address":"YOUR_ALGORAND_ADDRESS","quote":{/* fresh quote */},"slippage":0.005}'

Full copy-paste flows for quotes, positions, and swaps: examples.