Quickstart

Use the Caddy gateway URL as your base URL. Discovery, OpenAPI, and execution shapes are free; paid research and execution-quote routes require x402 USDC payment.

Option A: Use MCP (recommended for agent hosts)

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

{
  "mcpServers": {
    "amarok": {
      "url": "https://amarok-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 route catalog and payment policy.

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

2. Read OpenAPI

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

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

3. Probe free routes

Health and execution shapes should return 200 without payment headers.

curl -i https://amarok-api.compx.io/health
curl -i https://amarok-api.compx.io/v1/alpha/execution/shapes

4. Call a paid route

First call returns 402 with PAYMENT-REQUIRED. Retry with a signed payload.

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.

curl -i https://amarok-api.compx.io/v1/alpha/opportunities

curl -i https://amarok-api.compx.io/v1/alpha/opportunities \
  -H 'PAYMENT-SIGNATURE: <base64-json-payload>'

5. Unsigned execution quote (optional)

After research, list shapes (free), then POST a paid execution quote. Sign unsignedTxnsBase64 and submit via your own algod. meta.executionSubmitted is always false.

curl -i -X POST https://amarok-api.compx.io/v1/alpha/execution/quotes \
  -H 'content-type: application/json' \
  -H 'PAYMENT-SIGNATURE: <base64-json-payload>' \
  -d '{ /* shape + params — see OpenAPI */ }'