Arena Python SDK

Install

Python 3.10 or newer.

pip install arena-predictions            # httpx only
pip install "arena-predictions[pandas]"  # adds to_frame()

Ten lines

No key needed: a bet in words, its price on each venue, and the price gaps.

from arena_predictions import Arena

arena = Arena()
hit = arena.resolve("chiefs ml")[0]           # words to an instrument id
print(hit.instrument_id, hit.label, hit.kalshi[0].ticker, hit.kalshi[0].buy)

q = arena.quotes(hit.instrument_id)           # one instrument, every venue that prices it
for v in q.venues:
    print(v.venue, v.yes_bid, v.yes_ask, v.as_of, v.notes(q.label))

gaps = arena.gaps(league="nfl")               # ranked price gaps; a pair is arbitrage only after both venues' fees
print(gaps.to_frame().head())

What it reads, and from where

The publishable Supabase key and the website address are built in. They are not secrets: every browser and the iPhone app carry them, and they grant the signed-out role and nothing more.

The API key

The keyed calls need an Arena API key. The SDK never makes, rotates or revokes one: make it in Settings on the website (https://arena-predictions.com/settings#api-keys, signed in with Google or Apple). The key is sent to arena-predictions.com/api/v1 and nowhere else, and it only reads.

API keys cost nothing extra. Every keyed call counts against your account’s plan: 1,000 requests a month and 30 a minute without a plan, 10,000 and 60 with Arena Basic. The limits count today and refuse nothing yet.

export ARENA_API_KEY=arena_sk_...           # made in Settings on the website

from arena_predictions import Arena

arena = Arena()                              # reads ARENA_API_KEY
print(arena.me())                            # whose account, which scopes
page = arena.leaderboard("30d", "ai")        # 30d, 90d or all; people or ai
me = arena.account()                         # your own account (portfolio:read)
print(me.balanceDollars, me.run, me.pnlSinceResetDollars, me.lifetimePnlDollars)

Quotes and gaps: what the numbers mean

Every price is a probability from 0 to 1 for the instrument’s YES, whichever side of the venue’s market was read (yes_bid 0.57 is 57%). Venues come in a fixed order (Kalshi, Novig, Polymarket), never ranked by price, and every price carries its venue and its time (as_of). A venue whose contract differs from Kalshi’s says how, and VenueQuote.notes(label) gives those sentences in the website’s words; print them next to the prices.

A gap is the difference between venues on one side, in points (1 point is 1 cent). A pair buys YES on one venue and NO on another, with each venue’s taker fee worked out, and is labelled arbitrage only when both cost under $1 after both venues’ fees, under the rule on /docs/methodology. A label is not risk-free: prices move.

The eval board

The eval board scores models and people on their settled public picks, and never ranks by P&L (how it scores: /docs/execution#eval). eval_board() and eval_account(ref) read it with no key, and my_eval(window) reads your own rows with a key. The website shows the same board at /eval.

board = arena.eval_board(window="30d", cohort="same_games", kind="all", min_n=20)
for r in board.rows:
    print(r.rank_basis, r.board_rank, r.display_name, r.n_scored, r.log_loss, r.brier, r.clv_cents, r.roi_after_fees)

acct = arena.eval_account("Claude", window="30d")   # the picks behind a row
print(acct.instrument_ids)                          # the Arena instrument ids they were on

Read forecast_source before comparing rows: stated is the trader’s own probability, confidence an AI model’s confidence score, and implied the price paid, which is the market’s forecast, not the trader’s. For implied and confidence rows read edge_pts, closing-line value and roi_after_fees rather than log loss.

pandas

Every container has to_frame(), and to_frame(x) works on lists of anything the SDK returns. Time columns are datetime64[ns, UTC], and number columns with gaps are nullable Int64 or Float64.

asyncio, and a record's hash

AsyncArena has the same read methods as Arena, awaitable: each runs in a worker thread, so it never blocks the event loop. recompute_record_hash(rows) rebuilds a signed track record's record_hash from the trades it counts: one line per trade, P&L to two decimals and the close time in UTC with microseconds and Z (RECORD_HASH_FORMATS). The same formats are in the key document, /.well-known/arena-track-record-keys.json (record_hash), for a verifier in any language, and the CLI's arena record <name> --verify checks a record's signature without Python. Python SDK 0.3.0, not on PyPI yet.

Errors

Everything raises ArenaError or a subclass, with the server’s message and its machine code when it sent one. e.exit_code follows the arena CLI, so a script can sys.exit(e.exit_code): in Python SDK 0.2.0, 4 for a 401, 5 for a 402, 7 for no answer or a 5xx, and 6 for any other 4xx, a 429 and a 403 included. From Python SDK 0.3.0, not on PyPI yet, the code comes first: a 429 rate limit is 7 and retryable, quota_exceeded is 5, and session_required is 4.

What it does not do

• It does not trade: no buy, sell, limit order, cancel or settle. Paper trading happens on the website, in the app, or with the arena CLI or the MCP server signed in as yourself.
• It does not sign in, and it does not make, rotate or revoke keys.
• It does not read Kalshi’s order books, candlesticks or market catalog; those need a signed-in session and stay in the CLI and the MCP server.
• It sends no exchange price anywhere a visitor could not already see it.

Environment