API Docs

# one-off, nothing installed
npx arena-cli login

# or install the binary
npm install -g arena-cli
arena

There is nothing else to install for agent use. AXI is not a separate package, it is how arena behaves when its output is piped, so the same binary serves a person and an agent.

$ arena login
→ opening your browser to sign in with Google…
  (listening on http://127.0.0.1:53682/callback)
✔ signed in as sharp_joe · 100.00 spendable · season 2026-09

• arena login --provider apple signs in with Apple instead of Google.
• arena login --guest opens no browser and creates a guest account. Be warned: signing in with Google or Apple afterwards is a different user, and the guest account’s trades stay behind on it.
• arena login --device, the flow for a machine with no browser, is not in this release. On a headless box, sign in on a machine that has one and copy ~/.config/arena/credentials.json across, or use arena login --guest.
• Credentials go in your OS keychain, falling back to ~/.config/arena/credentials.json with mode 0600. The access token lives about an hour and refreshes itself; arena logout deletes the stored pair.

Flags that work everywhere

$ arena balance
Balance    84.30
Net worth  96.55
Season     2026-09

$ arena buy ARENA-EXAMPLE-1 --side yes --contracts 10
  NFL · KC vs BUF · Sep 10 — yes @ 62¢ ask (bid 58¢)
  stake 6.20 · balance 84.30 → 78.10
  Fills server-side at the live ask, so it may differ from this quote.
  Continue? [y/N] y
✔ filled at 63¢ · stake 6.30 · trade a1b2c3d4 (slippage +1¢ vs quote)

$ arena positions
TRADE     MARKET                       SIDE  ENTRY  NOW   P&L
a1b2c3d4  NFL · KC vs BUF · Sep 10     yes   63¢    67¢   +0.40

$ arena sell a1b2c3d4 --yes
✔ sold at 67¢ · +0.40

Three things worth knowing about that buy. The engine is market-order-only: you never set a price, and the fill happens server-side at the live ask, which is why the CLI reconciles the actual fill against the quote and tells you the slippage. --max-price refuses to submit when the quoted ask is above your ceiling. And every logical attempt carries a fresh idempotency key, so a network timeout can be retried with the same key without any risk of filling twice.

Agent mode triggers itself

The CLI is in agent mode when !process.stdout.isTTY (that is, whenever output is piped or captured) or when ARENA_AGENT=1 is set. There is nothing to configure. In agent mode:

• output is TOON, not tables, and never has spinners or colour;
• there are no prompts, ever. A mutation without --yes is a hard error, and the CLI will not wait on stdin;
• stdout carries data, stderr carries logs and diagnostics, so 2>/dev/null is always safe;
• every list reports totalCount, and an empty result prints an explicit count: 0 or emptyReason rather than nothing at all;
• every output ends with a help[] array of next-step command templates.

The home view

Bare arena is live state, not help text. An agent can orient itself in one call.

bin: arena
about: Arena — paper trading for prediction markets
mode: paper
season: 2026-09
balance: 84.30
netWorth: 96.55
openPositions: 3
help[3]: arena positions,arena leaderboard,arena buy <ticker> --side yes --contracts 10 --yes

TOON shape

The encoder follows TOON v4.1:

• a tabular array is key[N]{f1,f2}: with its rows indented one level;
• an array of primitives is inline: key[N]: a,b;
• an empty array is key: [], never key[0]:;
• a string is quoted when it is empty, padded, true, false, null or numeric-like, when it holds a colon, comma, quote, backslash, bracket, brace or control character, or when it starts with - or #. Internal spaces, dots and the middle dot need no quoting.

season: 2026-09
status: live
fieldSize: 282
published: 3
rankBasis: net_worth_at_cost
asOf: "2026-09-11T15:00:00Z"
mode: paper
leaderboard[3]{rank,name,returnPct,record}:
  4,sharp_joe,18.42,41-22-3
  11,kcnerd,9.1,19-15-0
  37,Lina B.,2.35,8-7-1
help[2]: arena trader sharp_joe,arena leaderboard --season 2026-08

An empty result is an answer, not a failure. It exits 0 and says why:

trader: sharp_joe
season: 2026-10
totalCount: 0
picks: []
emptyReason: No settled picks in season 2026-10 yet.
help[1]: arena trader sharp_joe picks --season 2026-09

Errors are structured too, and in agent mode they go to stdout so a captured run always parses:

error:
  code: trader_not_found
  status: 404
  detail: No published record exists for this trader id.
help[1]: arena leaderboard

--json prints the underlying JSON verbatim instead, in either mode. It is the stable, non-proprietary escape hatch and it is not going away.

Exit codes

Any other non-zero exit is an unexpected internal error, so treat it as a bug and report it rather than retrying in a loop.

# agent mode, no --yes: hard error, exits non-zero, never waits on stdin
$ arena buy ARENA-EXAMPLE-1 --side yes --contracts 10 | cat
error:
  code: confirmation_required
  detail: Mutations in agent mode require --yes. Nothing was sent.
help[1]: arena buy ARENA-EXAMPLE-1 --side yes --contracts 10 --yes
$ echo $?
2

Ambient context hook

A session-start hook lets the agent see current balance, open positions and the season before it acts, instead of spending a discovery round trip on it. Bare arena in agent mode prints exactly that, so the hook is one line of config: in Claude Code, ~/.claude/settings.json. (arena hook install, which writes this for you, is not in this release.)

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "arena" }] }
    ]
  }
}

arena: signed in
mode: paper
season: 2026-09
balance: 84.30
openPositions: 3
help[2]: arena positions,arena markets --league nba

Prompt your coding agent

Paste this into Claude Code, Cursor or any other coding agent to teach it the CLI in one shot.

You have the Arena CLI installed as `arena`. It is paper trading for sports
prediction markets, virtual money only, so nothing you do can spend real funds.

Start by running `arena` on its own. It prints my balance, my open positions and
the current season, so you do not need a discovery round trip.

The commands you will want:
  arena markets --league nba          open markets
  arena search "lakers"               find a market by text
  arena market <ticker>               one market in detail
  arena orderbook <ticker>            resting bids and asks
  arena positions                     open positions with P&L
  arena balance                       spendable points and net worth
  arena buy <ticker> --side yes --contracts 10 --yes
  arena sell <trade-id> --yes
  arena history                       settled trades

Your output is piped, so the CLI is already in agent mode: you get TOON instead
of tables, you are never prompted, and every mutation needs --yes or it fails.
Add --json to any command if you would rather parse JSON.

Exit codes: 0 ok, 2 bad usage, 4 not signed in, 5 needs Pro, 6 client error,
7 network or server error. Treat anything else as a bug.

Before you buy anything, read the orderbook and tell me the ask and the stake.
Never place or close a trade I did not ask for.

claude mcp add arena -- npx -y arena-mcp-server

For Claude Desktop and anything else that reads an mcpServers block, add:

{
  "mcpServers": {
    "arena": {
      "command": "npx",
      "args": ["-y", "arena-mcp-server"]
    }
  }
}

The stdio server acts as you, on your own machine, with your own session, the same trust shape as running the CLI yourself. A hosted, third-party MCP server is a different question and needs the scoped-grant work that API keys are the first half of.

Keys are created, listed and revoked here in the browser, signed in. There is deliberately no API for minting a key from a key: a leaked read-only key must not be able to mint itself a replacement and survive its own revocation. Revocation takes effect immediately on the next request.

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"
}

/api/v1/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.

Errors

Every failure uses one envelope, so you can branch on the code:

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

What a key can reach

The keyed API serves Arena-owned data only: leaderboards, published trader records, and the key owner’s own paper-trading results. Live market data from the exchanges Arena quotes is not redistributed through it. If you want live prices, use the CLI signed in as yourself. That is your own session, exactly like using the website.

Arena is paper trading. Every number these endpoints return is virtual and has no cash value. See how Arena works, the Terms of Use and the Privacy Policy, or get in touch.