REST Authentication

Base URL: https://api.clocktower.finance. Paths below are relative to that host (no /api prefix on the production API host).

MCP uses the same free and developer credentials. Pass Authorization: Bearer ctk_… in the MCP client headers when you want the developer lane. See MCP connection.

Use of the hosted API is subject to the Terms of Use.

Chain selection (?chainId=) is independent of auth. See Chain selection.

Method	When
None	Free tier — call endpoints with per-IP rate limits
Authorization: Bearer ctk_…	Developer tier — free API key (higher read limits)

Successful REST responses include an X-Clocktower-Lane header of free or developer.

Free tier

No credentials required. Send requests directly. Limits are per IP.

• Tight prepare/readiness budgets (simulation is expensive on shared RPC).
• Search caps: first ≤ 10; includeDetails=true not allowed.

Developer tier (API key)

Free developer keys raise read limits (per key, not IP). Keys are issued at developers.clocktower.finance (hashed at rest; plaintext shown once on create).

Using a key

curl -s https://api.clocktower.finance/catalog \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Replace <YOUR_API_KEY> with the full secret (including the ctk_ prefix).

Invalid or revoked keys return 401 (they do not fall back to free tier).

Product guidance

• Free and developer keys are for exploration and reads.
• Prepare/readiness is intentionally limited (on-chain simulation/gas estimate even though the server never relays txs).

See Rate limits.

Optional Basic Auth

HTTP Basic Auth is controlled by API_REQUIRE_BASIC_AUTH (default false).

CORS

Browser cross-origin requests are disabled by default. Ops must whitelist origins via API_CORS_ALLOWED_ORIGINS. CORS is not authentication and is not granted by a key.