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)

Paste the hosted Worker config into Cursor or Claude Desktop. You do not need the git repo. Confirm routes against live discovery first; then connect Streamable HTTP MCP.

Live discovery (free): https://amarok-api.compx.io/discovery
OpenAPI (free): https://amarok-api.compx.io/openapi.json
Worker MCP URL: https://amarok-mcp.compx.io/mcp (streamable-http, POST)

Paid MCP tools spend mainnet USDC via x402. Start with free tools (amarok_health, amarok_get_discovery, amarok_get_openapi, amarok_list_execution_shapes). There is no hosted dry-run. In-repo MCP e2e uses an in-process stub API with no mainnet USDC (npm run test -w @amarok/mcp). Local stdio against compose still hits x402 if you call paid tools.

Cursor

Save as ~/.cursor/mcp.json (user) or .cursor/mcp.json (project). Same JSON as mcp/mcp.json.example in the repo.

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

Claude Desktop

Same remote URL transport. Save as ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

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

GET https://amarok-mcp.compx.io/mcp returns 405 (no SSE). That is expected — Streamable HTTP uses POST. Verify with https://amarok-mcp.compx.io/.well-known/mcp or /health, not a browser GET. Full tool list: MCP documentation. Paid amarok_get_scan (and ranking tools that share the orderbook pass) are capped at 12 markets with a 45s orderbook budget so a cold scan finishes inside typical MCP client timeouts (~60s). Responses may set timedOut / capped. Operators: ALPHA_SCAN_ORDERBOOK_LIMIT=12, ALPHA_MAX_MARKETS_PER_SCAN=0, ALPHA_SCAN_TIMEOUT_MS=45000.

Local stdio (optional dry-run against compose)

From a clone of the monorepo after npm install. Points at local Caddy (http://127.0.0.1:8788), not the production Worker. Paid tools still settle x402 if that gateway is live; use the stub test suite to avoid spend.

{
  "mcpServers": {
    "amarok": {
      "command": "npx",
      "args": [
        "tsx",
        "mcp/src/index.ts"
      ],
      "env": {
        "AMAROK_API_URL": "http://127.0.0.1:8788"
      }
    }
  }
}

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 operation paths, path parameters, request/response schemas (including execution quotes), and x402 / payment metadata. Research GET routes currently return full payloads — there are no query filters yet.

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

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>'

Optional additive SKUs: GET /v1/alpha/bundle (one payment → opportunities + quotes + N markets) or POST /v1/alpha/session then AMAROK-SESSION on covered research GETs. Watchlist is per-request: POST /v1/alpha/watchlist then GET /v1/alpha/watchlist for deltas only. Per-request 402 remains the default. Do not replay PAYMENT-SIGNATURE.

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 */ }'