Arena Usage API

openapi: 3.2.0
info:
  title: Arena Usage API
  version: 1.15.0
  summary: 'Arena with an API key: read Arena-owned data, place paper orders with trade:write, and send live orders to your own venue account with a venue''s live-order scope.'
  description: 'Arena Predictions (arena-predictions.com) is paper trading for prediction markets at live prices, in a sandbox, and live orders through the key owner''s own venue credentials. Paper is the default on every endpoint here (mode "paper"): a paper trade fills in Arena''s sandbox and is not sent to a venue. A live order is sent only when a request says execution kalshi or poly-intl with a key made with trade:write:kalshi or trade:write:poly-intl. It goes to the key owner''s own Kalshi or Polymarket International account with the venue credentials saved in Settings: real money at the venue, under the venue''s rules and terms. Arena is not a broker and never holds your funds. Polymarket International is not for US persons, and ProphetX orders are switched off (trade:write:prophetx is not issued, so execution prophetx is refused with 403 insufficient_scope; a key that carries the scope gets 503 trading_off). Keys read by default and reach Arena-owned data only: the key''s own identity and account, the leaderboards and published trader records with their resets and settled picks. Keys are managed with the signed-in browser session, never with a key. No exchange ticker, market title, entry price or venue price appears in a paper answer or a read while the venue-data switch is off; the owner''s own portfolio carries the owner''s own paper numbers (a resting order''s limitCents, a position''s costDollars and contracts). A live order''s answer names the venue''s own market and price (ticker, priceCents). Balances carry over: every account starts with 100,000 paper dollars, and a reset (at most one every 30 days, shown on a public profile) starts a new run. 1.2.0: seasons removed (no season field anywhere), leaderboard windows and kinds, trader resets, GET /account. 1.3.0: accounts are private by default. A private trader answers private: true with every P&L and rank null (resets and busts 0) and an empty pick list; a public trader whose earlier trades are still hidden has numbersShown: false and no P&L or rank. The key owner reads their own picks (each with placedPrivate and shown) and their own eval rows (GET /me/eval) with portfolio:read. No key can make an account public. 1.4.0: keys are managed by a person''s session, on the website or as a signed-in CLI''s session token (arena keys), never by a key; keys rotate with a grace period; every keyed answer carries the plan and its counts (RateLimit-*, Arena-Quota-*, Arena-Plan) and GET /usage says where the account stands; a new scope, markets:read, reads instruments, games and quotes; GET /portfolio and /portfolio/trades read the owner''s positions, orders and trades. Venue references and venue prices are served only while the venue-data switch is on (it ships off): until then the quotes routes answer 403 venue_data_off and nothing keyed names a ticker or a venue''s price. 1.5.0: GET /eval, the public eval board (records:read), each row with 95% intervals clustered by game. 1.6.0: GET /traders/{traderId}/track-record, a trader''s Ed25519-signed 90-day record exactly as Arena signed it (records:read; it names Kalshi series inside its signed bytes, so it is served only while the venue-data switch is on), and tiedWithAbove on each eval row (null while this row''s or the row above''s interval is unknown). 1.7.0: a key created with trade:write (only when asked for by name: the Settings checkbox, arena keys create --trade, or scopes in the body) places paper orders with POST /portfolio/orders and cancels them with DELETE /portfolio/orders/{orderId}, at Kalshi''s paths. Market and limit orders, buys by instrument or ticker and sells of a whole position, each with an idempotencyKey: the same key again answers the stored order with replayed: true and places nothing. Hard trade limits are always enforced: per key 10 new orders a minute and 50 a day, and 20 sells and cancels a minute; per account, across every key and connected app, 20 new orders a minute, 100 a day, and 40 sells and cancels a minute.'
  termsOfService: https://arena-predictions.com/terms
  contact:
    name: Arena
    email: support@zbgcllc.com
    url: https://arena-predictions.com/support
servers:
- url: https://arena-predictions.com/api/v1
  description: The Arena API. Paper trading, Arena's sandbox, is the default on every account. An order is sent to a venue only when the request says execution and the key carries that venue's scope.
tags:
- name: Usage
  description: Where the key's account stands against its plan. Any valid key; never counted.
paths:
  /usage:
    get:
      tags:
      - Usage
      operationId: getUsage
      summary: Get usage
      description: 'The key''s account against its plan: requests this month (all keys together) and this minute, when each resets, this key''s own count, and whether the limits refuse requests yet. Any valid key; never counted.'
      security:
      - apiKey: []
      responses:
        '200':
          description: Where the account stands.
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            Arena-Quota-Limit:
              $ref: '#/components/headers/Arena-Quota-Limit'
            Arena-Quota-Remaining:
              $ref: '#/components/headers/Arena-Quota-Remaining'
            Arena-Quota-Reset:
              $ref: '#/components/headers/Arena-Quota-Reset'
            Arena-Plan:
              $ref: '#/components/headers/Arena-Plan'
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
        '401':
          description: Missing, malformed, unknown, revoked or expired key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Usage could not be read right now.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  headers:
    X-Request-Id:
      description: Quote it when asking for help.
      schema:
        type: string
    Arena-Plan:
      description: none (signed in, without a plan), basic, builder, desk or enterprise.
      schema:
        type: string
    RateLimit-Remaining:
      description: Requests left in this minute.
      schema:
        type: integer
    RateLimit-Reset:
      description: Seconds until the minute window resets.
      schema:
        type: integer
    Arena-Quota-Limit:
      description: The plan's requests per month (UTC).
      schema:
        type: integer
    Arena-Quota-Remaining:
      description: Requests left this month.
      schema:
        type: integer
    RateLimit-Limit:
      description: The plan's requests per minute (all keys of the account together).
      schema:
        type: integer
    Arena-Quota-Reset:
      description: Seconds until 00:00 UTC on the 1st.
      schema:
        type: integer
  schemas:
    Usage:
      type: object
      required:
      - tier
      - month
      - minute
      - key
      - enforced
      properties:
        tier:
          type: string
          enum:
          - none
          - basic
          - builder
          - desk
          - enterprise
          description: 'none: signed in, without a plan.'
        month:
          type: object
          required:
          - limit
          - used
          - resetsAt
          properties:
            limit:
              type: integer
            used:
              type: integer
            resetsAt:
              type: string
              format: date-time
        minute:
          type: object
          required:
          - limit
          - remaining
          - resetsAt
          properties:
            limit:
              type: integer
            remaining:
              type: integer
            resetsAt:
              type: string
              format: date-time
        key:
          type: object
          required:
          - prefix
          - requestsThisMonth
          - lastUsedAt
          properties:
            prefix:
              type: string
            requestsThisMonth:
              type: integer
            lastUsedAt:
              type:
              - string
              - 'null'
              format: date-time
        enforced:
          type: boolean
          description: 'False while the limits only count (observe mode): nothing is refused.'
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Stable machine token. Branch on this, never on message.
              enum:
              - invalid_request
              - unauthorized
              - invalid_token
              - insufficient_scope
              - guest_account
              - scope_not_available
              - key_limit_reached
              - key_not_found
              - trader_not_found
              - account_not_found
              - route_not_found
              - method_not_allowed
              - internal_error
              - session_required
              - key_creation_limited
              - rate_limited
              - quota_exceeded
              - venue_data_off
              - consolidated_book_off
              - instrument_not_found
              - game_not_found
              - membership_required
              - trading_off
              - kalshi_key_missing
              - kalshi_rejected
              - poly_intl_key_missing
              - poly_intl_rejected
              - us_not_eligible
              - prophetx_key_missing
              - prophetx_rejected
              - not_configured
              - live_trading_unavailable
              - idempotency_key_reused
              - insufficient_balance
              - market_not_found
              - no_tradable_listing
              - market_not_open
              - market_resolved
              - no_liquidity
              - price_moved
              - trade_not_found
              - already_closed
              - order_not_found
              - organization_not_found
              - organization_forbidden
            message:
              type: string
              description: Human sentence. May change.
            retryAfterSeconds:
              type: integer
              minimum: 1
              description: 'On every 429: the same number as the Retry-After header.'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: arena_sk_ + 43 base64url characters
      description: 'Authorization: Bearer arena_sk_... (the x-arena-key header is accepted too). Keys are made in Settings (https://arena-predictions.com/settings#api-keys) or with `arena keys create`, shown once, stored hashed.'
    session:
      type: apiKey
      in: cookie
      name: sb-access-token
      description: The signed-in browser session (Google or Apple). Used only for key management, same-origin JSON requests only. An API key presented here is refused (401 session_required).
    sessionBearer:
      type: http
      scheme: bearer
      bearerFormat: Supabase access token (JWT) of a signed-in person
      description: 'A signed-in person''s session token, as the CLI sends it after arena login. Key management checks it with the auth server (JSON bodies required; an arena_sk_ key there is 401 session_required). POST /backtest, POST /evals, GET /runs and GET /runs/{run_id} take it in place of a key and forward it to the backtest function, which checks it with the auth server. A bearer that starts with arena_sk_ is always read as a key. Never a guest session (403 guest_account) or a connected app''s OAuth token (401 session_required). Every other keyed route answers it 401 unauthorized: that route takes an API key.'
externalDocs:
  description: Arena API docs
  url: https://docs.arena-predictions.com