Arena HTTP API

REST API

https://arena-predictions.com/api/v1

HTTPS only. Requests over plain HTTP are redirected, and a key sent over HTTP should be revoked. There is one environment: every account is a paper account, so a key acts on your real Arena account and a trade placed through the CLI is a real paper trade on your record.

Versioning

The API is versioned in the path. Within v1 changes are additive: new endpoints and new optional fields, never a renamed or removed one. A breaking change ships as /api/v2, with v1 kept for at least 180 days and the retirement dated in the changelog.

Specifications

GET /status needs no key and says whether the API is up. GET /openapi.json is the OpenAPI 3.1 description of every live endpoint, and /llms.txt is the short version for a language model.

The header

Authorization: Bearer arena_sk_…

A key is arena_sk_ followed by 43 base64url characters (256 bits). x-arena-key: arena_sk_… is accepted as an alternative header for clients that cannot set Authorization. A missing or bad credential answers 401 with a WWW-Authenticate: Bearer challenge; a valid key with the wrong scope answers 403 insufficient_scope.

Key lifecycle

• Only the hash of a key is stored. The plaintext exists in one HTTP response, at creation; lose it and you revoke it and create another. The list shows the first 16 characters so you can tell your keys apart.
• An account holds at most 10 active keys. A key may carry an expiry (1 to 365 days) and is revoked instantly; the next request that presents it gets 401 invalid_token.
• Key management is done with your signed-in browser session, never with a key. A leaked read-only key must not be able to mint itself a replacement and outlive its own revocation, so there is deliberately no key-from-key endpoint. Creating and revoking a key accept same-origin requests only: a script that sends your session cookie must also send Origin: https://arena-predictions.com, and a create must be Content-Type: application/json.
• There is no guest or anonymous access. Every key belongs to a Google or Apple account, and every trade and record belongs to the person who signed in.

Scopes

Create a key

Status, no key

curl -sS https://arena-predictions.com/api/v1/status

{
  "ok": true,
  "version": "v1",
  "mode": "paper",
  "season": "2026-09",
  "time": "2026-09-22T04:10:00Z"
}

Who am I, with a key

curl -sS https://arena-predictions.com/api/v1/me \
  -H "Authorization: Bearer arena_sk_your_key_here"

{
  "user": { "id": "0f4c…", "displayName": "sharp_joe" },
  "key": {
    "prefix": "arena_sk_4Fq1XyZ",
    "scopes": ["records:read", "portfolio:read"]
  },
  "mode": "paper"
}

GET /me needs a valid key but no particular scope. It is how an agent discovers whose account it is acting for and what it is allowed to do, before it tries anything that could fail.

The same question from the CLI

$ arena whoami
userId          4d2f8c1e-9b0a-4c6e-8f21-3a7b5d9e0c12
displayName     sharp_joe
isPro           true
balanceDollars  $1,046.00
monthKey        2026-09

Names

JSON fields are camelCase (displayName, expiresInDays). Query parameters are snake_case. Enum values are lowercase (active, revoked, paper). Resources are plural nouns; a user’s own data lives under /portfolio, and the paths under it are Kalshi’s.

Units are in the name

*Cents is an integer price in cents, 1 to 99, for the side named. *Dollars and dollars are paper dollars as JSON numbers rounded to two decimals (a trailing zero is not represented: 984.3 is $984.30). *Count is an integer. *Pct is a percentage as a number, not a fraction.

Prices

A contract pays $1 if it settles yes. Stake = contracts × cents ÷ 100. A market order fills now, buying at the live ask and selling at the live bid. A limit order fills only at its price or better, and otherwise rests. No partial fills either way: an order fills whole or not at all.

Times

Instants are RFC 3339 UTC strings at second precision ending in Z, named *At (createdAt). Seasons are calendar months in America/New_York, written YYYY-MM and named season or monthKey. The CLI’s candlestick timestamps are Unix seconds, named *Ts.

Identifiers

Keys, traders and trades are UUIDs. Market tickers are uppercase strings and are opaque: never parse a ticker to infer anything. Arena instrument ids (ins_ plus 12 characters) are permanent and opaque too; see the universal ticker.

Every keyed response

Says "mode": "paper", and answers 201 on create and 200 with the updated resource on revoke. Key management, GET /me and every error are Cache-Control: no-store; a successful records read is Cache-Control: private, max-age=30. Keyed endpoints send no CORS headers: a key belongs in a server, a CLI or an agent runner, never in browser code. There is no streaming under a key; poll.

Identify your client

Send x-arena-client: yourapp/1.2.0 (or a descriptive User-Agent). The CLI and the MCP server do. It is not enforced today; it is the hook for telling a client its version is too old instead of breaking it. Trades the CLI or the MCP server opens at once, and orders they place, keep the tag they were sent with (cli/0.3.0, mcp/0.3.0). A limit order that rests and fills later keeps the tag on the order, not on the trade the fill creates, and sells are not tagged. That tag is self-reported and not verified, and a tag that is not cli, mcp, web or ios plus a version is not kept.

Where Arena differs from Kalshi

• Field names are camelCase here and snake_case on Kalshi. Paths and query parameters are snake_case on both.
• Money is a JSON number in paper dollars here; Kalshi sends fixed-point dollar strings ("0.5600"). Prices are integer cents here; Kalshi’s are dollar strings between 0 and 1.
• Instants are always *At RFC 3339 strings here; Kalshi mixes _time strings and _ts Unix seconds.
• A key is a bearer token here; Kalshi signs each request with an RSA key. A retried trade returns the original trade here; Kalshi answers 409 on a duplicate client_order_id.

How it works

GET /leaderboard and GET /traders/{traderId}/picks take limit (an integer from 1 to 100, with a documented default) and cursor, and answer with the rows and nextCursor, which is null on the last page. Pass nextCursor back as cursor and loop until it is null. A malformed cursor is 400 invalid_request. Lists do not carry a total count. Kalshi's lists work the same way, with cursor in the body instead of nextCursor.

Whole collections

GET /api_keys is not paginated: an account holds at most 10 active keys. In the CLI every list carries totalCount instead.

The envelope

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="arena", error="invalid_token", error_description="API key is invalid, revoked or expired."
Cache-Control: no-store

{
  "error": {
    "code": "invalid_token",
    "message": "API key is invalid, revoked or expired."
  }
}

code is a stable machine token that will not be reworded. message is a human sentence and may change. Kalshi’s envelope is the same two fields at the top level; Arena nests them under error.

Codes

Status codes mean what HTTP says they mean. Each row says whether retrying can help and which exit code the CLI turns it into.

Today

The keyed endpoints enforce no per-key limit yet. Please keep each key under 60 requests a minute, and use nextCursor rather than re-reading a whole list. Treat any 429 as retryable: honour Retry-After when it is present, otherwise back off exponentially from one second.

Before a limit applies

Any per-key limit will be announced in the changelog before it applies, with the headers that report it documented here first.

Client-side caps

The MCP server caps itself, as runaway protection for an agent in a loop: by default 60 reads and 10 trades a minute, and 50 trades a day. That cap is local to the server and separate from anything the API does. The CLI has no cap of its own.

Safe to repeat

Every GET. DELETE /api_keys/{id}: the second call answers 404 key_not_found, which means the key is already gone. POST /api_keys is not idempotent: every call mints a new key.

Reads and key management

Retry a network failure, a timeout, a 429 or a 5xx, with backoff. A 4xx other than 429 is final; fix the request.

Trades

Through the CLI today: every logical attempt carries a fresh UUID idempotencyKey. The same key is reused only when the attempt got no answer at all (a transport failure), and the server then returns the original trade rather than filling twice. An answered failure, 4xx or 5xx, is never retried with the same key. A sell is never retried.

In practice you use these through the panel in the Authentication section; they are documented so what the panel does is not a mystery.

curl -sS https://arena-predictions.com/api/v1/api_keys \
  -H "Cookie: <your signed-in browser session>"

{
  "keys": [
    {
      "id": "8c0b6f1e-2a3d-4e5f-9a7b-1c2d3e4f5a6b",
      "label": "Claude Code on the laptop",
      "tokenPrefix": "arena_sk_4Fq1XyZ",
      "scopes": ["records:read", "portfolio:read"],
      "status": "active",
      "createdAt": "2026-09-15T18:02:11Z",
      "lastUsedAt": "2026-09-22T03:58:40Z",
      "expiresAt": null,
      "revokedAt": null
    }
  ],
  "count": 1
}

curl -sS -X POST https://arena-predictions.com/api/v1/api_keys \
  -H "Cookie: <your signed-in browser session>" \
  -H "Origin: https://arena-predictions.com" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Claude Code on the laptop", "scopes": ["records:read", "portfolio:read"], "expiresInDays": 90 }'

{
  "key": {
    "id": "8c0b6f1e-2a3d-4e5f-9a7b-1c2d3e4f5a6b",
    "label": "Claude Code on the laptop",
    "tokenPrefix": "arena_sk_4Fq1XyZ",
    "scopes": ["records:read", "portfolio:read"],
    "status": "active",
    "createdAt": "2026-09-22T04:10:00Z",
    "lastUsedAt": null,
    "expiresAt": "2026-12-21T04:10:00Z",
    "revokedAt": null
  },
  "token": "arena_sk_4Fq1XyZ…(43 characters after the prefix)",
  "warning": "Copy this key now. It is shown once and cannot be recovered, so if you lose it, revoke it and create another."
}

curl -sS -X DELETE https://arena-predictions.com/api/v1/api_keys/8c0b6f1e-2a3d-4e5f-9a7b-1c2d3e4f5a6b \
  -H "Cookie: <your signed-in browser session>" \
  -H "Origin: https://arena-predictions.com"

{
  "key": {
    "id": "8c0b6f1e-2a3d-4e5f-9a7b-1c2d3e4f5a6b",
    "label": "Claude Code on the laptop",
    "tokenPrefix": "arena_sk_4Fq1XyZ",
    "scopes": ["records:read", "portfolio:read"],
    "status": "revoked",
    "createdAt": "2026-09-22T04:10:00Z",
    "lastUsedAt": null,
    "expiresAt": "2026-12-21T04:10:00Z",
    "revokedAt": "2026-09-22T04:12:30Z"
  },
  "revoked": true
}

Every successful response says "mode": "paper". Money is paper dollars; a season is an America/New_York calendar month. Sample ids and names are placeholders.

curl -sS "https://arena-predictions.com/api/v1/leaderboard?limit=2" \
  -H "Authorization: Bearer arena_sk_your_key_here"

{
  "season": "2026-09",
  "rows": [
    { "rank": 1, "traderId": "4d2f8c1e-9b0a-4c6e-8f21-3a7b5d9e0c12", "displayName": "sharp_joe", "netWorthDollars": 2683.84 },
    { "rank": 2, "traderId": "11111111-1111-4111-8111-111111111111", "displayName": "kcnerd", "netWorthDollars": 1089.3 }
  ],
  "nextCursor": "2:11111111-1111-4111-8111-111111111111",
  "mode": "paper"
}

curl -sS https://arena-predictions.com/api/v1/traders/sharp_joe \
  -H "Authorization: Bearer arena_sk_your_key_here"

{
  "trader": {
    "traderId": "4d2f8c1e-9b0a-4c6e-8f21-3a7b5d9e0c12",
    "displayName": "sharp_joe",
    "season": { "season": "2026-09", "rank": 1, "netWorthDollars": 2683.84 },
    "seasons": [
      { "season": "2026-08", "startDollars": 100, "endDollars": 140, "netDollars": 40 }
    ]
  },
  "mode": "paper"
}

curl -sS "https://arena-predictions.com/api/v1/traders/sharp_joe/picks?limit=2" \
  -H "Authorization: Bearer arena_sk_your_key_here"

{
  "picks": [
    {
      "pickId": "6f1c2a3b-4d5e-4f60-8a71-b2c3d4e5f607",
      "side": "yes",
      "result": "won",
      "stakeDollars": null,
      "pnlDollars": 3.7,
      "openedAt": "2026-09-21T16:58:02Z",
      "closedAt": "2026-09-21T20:31:44Z",
      "instrumentId": "ins_0123456789AB",
      "marketLabel": "KC -3.5"
    },
    {
      "pickId": "7a1c2a3b-4d5e-4f60-8a71-b2c3d4e5f608",
      "side": "no",
      "result": "lost",
      "stakeDollars": 6.3,
      "pnlDollars": -6.3,
      "openedAt": "2026-09-20T01:12:40Z",
      "closedAt": "2026-09-20T04:05:09Z",
      "instrumentId": null,
      "marketLabel": null,
      "marketLabelReason": "no_arena_label"
    }
  ],
  "nextCursor": null,
  "mode": "paper"
}

Calling one answers 404 route_not_found. Each ships with a dated changelog entry, and market identity in any portfolio response will be an Arena-authored label until the exchange data licence has been read.