Partner read API

Quickstart

1. Get a key

• Local / staging: set API_V1_DEV_KEY (or leave unset and the process mints a one-shot ott_dev_… key when API_KEYS is empty and env is not production). Print it from process logs / your secret store — never commit it.
• Production: set API_KEYS as id:sha256hex:scopes (comma-separated). Scopes: read:firms read:payouts read:cash read:boards read:meta or read:*.
• Human docs stay public at /docs/api. Machine spec: /v1/openapi.json.

2. Call with Bearer or X-Api-Key

# Health (no key)
curl -sS https://onthetape.io/v1/health | jq .

# Firms (24h ranking)
curl -sS -H "Authorization: Bearer $ONTATAPE_API_KEY" \
  'https://onthetape.io/v1/firms?window=24h&limit=20' | jq .

# Recent verified payouts
curl -sS -H "X-Api-Key: $ONTATAPE_API_KEY" \
  'https://onthetape.io/v1/payouts?limit=30' | jq .

# Cash on hand (all mapped RiseUSD treasuries)
curl -sS -H "Authorization: Bearer $ONTATAPE_API_KEY" \
  'https://onthetape.io/v1/cash-on-hand?limit=50' | jq .

# One firm treasury
curl -sS -H "Authorization: Bearer $ONTATAPE_API_KEY" \
  'https://onthetape.io/v1/firms/tradeify-futures/cash-on-hand' | jq .

Auth

Send the raw API key (not the SHA-256 digest) on every keyed request.

• Authorization: Bearer <key>
• or X-Api-Key: <key>

Public vs keyed

• Public (no key): /docs/api, /v1/health, /v1/openapi.json
• Keyed: all other /v1/* routes (firms, payouts, cash-on-hand, search, boards, meta, …)

Missing / invalid key → 401 unauthorized. Missing scope → 403 forbidden.

Rate limits

Default: 120 requests / 60 seconds per API key (API_V1_RATE_LIMIT). Exceeding the quota returns 429 rate_limited with Retry-After: 60.

Money

All money fields are objects — never JSON numbers:

{
  "amount": "1234.56",
  "currency": "USD"
}

Parse amount as a decimal string. Currency is always USD for v1.

Pagination

Cursor style on list endpoints. Query: limit (default 50, max 200) and cursor.

{
  "pagination": {
    "next_cursor": "c32",
    "has_more": true,
    "limit": 50,
    "count": 50
  }
}

When has_more is true, pass next_cursor as cursor on the next request. Opaque — do not invent cursors.

as_of / freshness

Every successful envelope includes meta.generated_at, meta.as_of, meta.request_id, and meta.api_version.

• as_of is the observation time for the underlying book (may equal generated_at).
• Freshness matches the website (Rise listen ~20s; cached stats/events ~50s TTL).
• Treasury history endpoints currently return the latest snapshot only until the site publishes a series.

Endpoints

Full schema: /v1/openapi.json. Windows: 24h 7d 30d 365d ytd alltime.

Error catalog

Errors are JSON with HTTP status and a stable error.code:

{
  "error": {
    "code": "unauthorized",
    "message": "…",
    "request_id": "req_…",
    "details": {}
  }
}

OpenAPI

Machine-readable OpenAPI 3.1 document (public, no key):

curl -sS https://onthetape.io/v1/openapi.json | jq '.info, (.paths | keys)'

Full sync patterns and money/as_of rules also live in the repo at docs/integration.md.

MCP server

Stdio MCP server at site/mcp_server.py. Tools wrap the same /v1 handlers (HTTP when a base URL is set; in-process for unit tests).

Environment

Run

export ONTATAPE_API_KEY=your_key
export ONTATAPE_API_BASE=https://onthetape.io
python3 site/mcp_server.py

Docker Compose: docker compose --profile mcp run --rm mcp (sets base to the compose api service).

Tools

Cursor (mcp.json)

{
  "mcpServers": {
    "onthetape": {
      "command": "python3",
      "args": ["/absolute/path/to/site/mcp_server.py"],
      "env": {
        "ONTATAPE_API_KEY": "your_key",
        "ONTATAPE_API_BASE": "https://onthetape.io"
      }
    }
  }
}

Never commit the key. Prefer a secret store / local env override.