> ## Documentation Index > Fetch the complete documentation index at: https://docs.arena-predictions.com/llms.txt > Use this file to discover all available pages before exploring further. # Place a paper order > Places an order for the key owner. The default is a paper order, as the CLI and the MCP server do: nothing is sent to Kalshi or any venue. execution kalshi sends a live Kalshi order (scope trade:write:kalshi) through the live door and does not touch the paper book. execution poly-intl sends a live Polymarket International order (scope trade:write:poly-intl) and refuses a US visitor. Polymarket US is not offered. Send X-Arena-Org to place a paper order on that organization's paper sandbox; without the header the paper order is on the personal account. An unknown or forbidden organization places nothing. A market order fills now at the live price or is refused. A limit order fills at limitPriceCents or better, rests until it fills, is canceled or expires (gtc), or is canceled at once when it does not fill (ioc, fok). Opening a position needs Arena Basic. Every paper order counts against the hard trade limits (per key 10 new orders a minute and 50 a day, 20 sells and cancels a minute; per account 20, 100 and 40), which are always enforced. No ticker, title or price in the paper answer while the venue-data switch is off. ## OpenAPI ````yaml /openapi.json post /portfolio/orders openapi: 3.1.0 info: title: Arena API version: 1.11.0 summary: >- Arena Predictions paper trading with an API key: read, and place paper orders with trade:write. Arena-owned data only. description: >- Arena Predictions (arena-predictions.com) is a sandbox for paper trading prediction markets at live prices. Every endpoint here serves Arena's sandbox, where every trade is a paper trade (mode "paper"); routing to live trading is coming. Keys are read-only 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 any keyed response; the owner's own portfolio carries the owner's own paper numbers (a resting order's limitCents, a position's costDollars and contracts). 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. 1.8.0: GET /traders/{traderId}/track-record asks promote-record for audience=keyed and is served while the venue-data switch is off (records:read). That envelope has the same scores, signed with the same key, and names no Kalshi series ticker and no venue. Quotes still answer 403 venue_data_off until the switch is on. The CLI, the Python SDK and hosted MCP verify still read the public envelope, which names series. 1.9.0: POST /backtest (markets:read) forwards a paper replay of settled Kalshi game-winner markets to the backtest edge function. The JSON body is forwarded and the function's JSON is returned, with mode paper. GET and every other method answer 405 method_not_allowed and are not forwarded. 1.10.0: X-Arena-Org, an organization id, on GET /portfolio, GET /portfolio/trades, POST /portfolio/orders and DELETE /portfolio/orders/{orderId}. When the header is present those calls use that organization's paper sandbox. When it is absent they use the key owner's personal paper account. A value that is not an organization id is 400 invalid_request. An unknown organization is 404 organization_not_found and one this key cannot use is 403 organization_forbidden. The personal account is never the fallback, and the header does not select a Combine evaluation account. Paper only. 1.10.1: GET /organizations lists the organizations a personal API key belongs to. The call is forwarded to the organizations edge function with the caller's key, and the function's JSON is returned with mode paper. Each organization's id is what X-Arena-Org takes on the portfolio and paper-order routes. Any valid key, no particular scope. Paper only. 1.10.2: GET /portfolio and GET /portfolio/trades with X-Arena-Org return that organization's paper sandbox (cash, positions, resting orders and trades) and organization.slug. They do not return the personal account. 1.11.0: GET /history, GET /history/candles, GET /history/as_of and GET /history/export (markets:read) forward the query string to the Fly history service. The caller's key is checked here. The Fly server key stays on the server and is sent as x-arena-server-key to /srv/history*. The service's JSON is returned unchanged, and export may be CSV. While the venue-data switch is off these answer 403 venue_data_off and Fly is not called. A 400 or a non-auth 403 from the service keeps that status. A Fly 401 (the server key was refused) is 503, so a good caller key is not reported invalid. GET and HEAD only. Paper only. The keyless website routes (/api/quotes/{instrumentId}, /api/quotes/batch, /api/gaps, /api/gaps/{instrumentId}) are described in their own document, /openapi-public.json. 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. Every account on it trades in the sandbox (paper trading); routing to live trading is coming. security: [] tags: - name: Status description: Is the API up. - name: Identity description: >- Whose account a key acts for, which organizations it belongs to, and what it may do. - name: API keys description: >- Create, list, rotate and revoke keys, at the same path Kalshi uses. A person's session only (the website, or a signed-in CLI's session token): a key can never mint, rotate or revoke a key. - name: Records description: >- Arena's public records: the leaderboards, trader records with their resets, and settled picks. Scope records:read. Arena-owned data only: no exchange tickers, market titles, entry prices or live prices. Points equal paper dollars 1:1. - name: Portfolio description: >- The key owner's own paper account, positions, orders and trades. Scope portfolio:read. Send X-Arena-Org to read an organization sandbox instead. Arena-owned data only while the venue-data switch is off. - name: Markets description: >- Arena's instruments and games, venue quotes, POST /backtest (a paper game-winner replay), and GET /history* (Fly price history). Scope markets:read. Venue references, prices and history only while the venue-data switch is on. - name: Trading description: >- Place and cancel paper orders for the key owner. Scope trade:write, which a key carries only when its creator asked for it. Send X-Arena-Org to trade that organization's paper sandbox. Paper is the default: nothing is sent to a venue unless execution is kalshi (trade:write:kalshi) or poly-intl (trade:write:poly-intl, Polymarket International only). Polymarket US is not offered. - name: Usage description: >- Where the key's account stands against its plan. Any valid key; never counted. externalDocs: description: Arena API docs url: https://docs.arena-predictions.com paths: /portfolio/orders: post: tags: - Trading summary: Place a paper order description: >- Places an order for the key owner. The default is a paper order, as the CLI and the MCP server do: nothing is sent to Kalshi or any venue. execution kalshi sends a live Kalshi order (scope trade:write:kalshi) through the live door and does not touch the paper book. execution poly-intl sends a live Polymarket International order (scope trade:write:poly-intl) and refuses a US visitor. Polymarket US is not offered. Send X-Arena-Org to place a paper order on that organization's paper sandbox; without the header the paper order is on the personal account. An unknown or forbidden organization places nothing. A market order fills now at the live price or is refused. A limit order fills at limitPriceCents or better, rests until it fills, is canceled or expires (gtc), or is canceled at once when it does not fill (ioc, fok). Opening a position needs Arena Basic. Every paper order counts against the hard trade limits (per key 10 new orders a minute and 50 a day, 20 sells and cancels a minute; per account 20, 100 and 40), which are always enforced. No ticker, title or price in the paper answer while the venue-data switch is off. operationId: createOrder parameters: - name: X-Arena-Org in: header required: false schema: type: string maxLength: 63 description: >- Organization id. When present, this call uses that organization's paper sandbox. When absent, the key owner's personal paper account. A value that is not an organization id is 400 invalid_request. An unknown organization is 404 organization_not_found and one this key cannot use is 403 organization_forbidden. The personal account is never the fallback. Paper only. This header does not select a Combine evaluation account. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OrderRequest' example: action: buy type: limit instrumentId: ins_0123456789AB side: 'yes' count: 10 limitPriceCents: 40 timeInForce: gtc idempotencyKey: 1b4e28ba-2fa1-41d2-883f-0016d3cca427 responses: '200': description: >- A replay: this idempotencyKey was used before for the same order. Nothing new was placed. 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/OrderResult' '201': description: >- Placed: executed, resting, or canceled (an ioc or fok that did not fill). 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/OrderResult' '400': description: >- invalid_request (the message names the field), or insufficient_balance. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: >- Missing, malformed, unknown, revoked or expired key. Carries a WWW-Authenticate: Bearer challenge. content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: >- membership_required: opening a position needs Arena Basic. Sells work without it. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- insufficient_scope: the key does not carry trade:write. organization_forbidden: X-Arena-Org names an organization this key cannot use. Nothing was placed on the personal account. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- instrument_not_found, market_not_found, trade_not_found (a sell), or organization_not_found. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- Nothing placed: idempotency_key_reused, no_tradable_listing, market_not_open, market_resolved, no_liquidity, price_moved (past maxPriceCents or minPriceCents), or already_closed (a sell of a position that is no longer open). content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- rate_limited: over a hard trade limit (always enforced), or over the plan's requests while those limits are enforced; or quota_exceeded. Nothing placed. error.retryAfterSeconds equals Retry-After. headers: Retry-After: $ref: '#/components/headers/Retry-After' 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/Error' '503': description: >- trading_off: trading with API keys is switched off right now; nothing placed. internal_error: the key could not be checked, or Arena could not confirm the order; retry after Retry-After with the same idempotencyKey, which never places twice. content: application/json: schema: $ref: '#/components/schemas/Error' security: - apiKey: - trade:write - apiKey: - trade:write:kalshi - apiKey: - trade:write:poly-intl components: schemas: OrderRequest: type: object additionalProperties: false required: - type - idempotencyKey description: >- A buy names instrumentId or ticker, side and count. A sell names tradeId and covers the whole open position. A limit order adds limitPriceCents. Unknown fields are refused (400), so a typo never changes an order. properties: action: type: string enum: - buy - sell default: buy type: type: string enum: - market - limit description: >- market: fills now at the live price or is refused. limit: fills at limitPriceCents or better, or rests (gtc), or is canceled (ioc, fok). idempotencyKey: type: string format: uuid description: >- One per order. The same key again answers the stored order with replayed: true and places nothing; the same key with a different order is 409 idempotency_key_reused. Retry with the same key after a timeout or a 503. clientOrderId: type: string format: uuid description: Kalshi's name for idempotencyKey. Send one of the two. instrumentId: type: string pattern: ^ins_[0-9A-HJKMNP-TV-Z]{12}$ description: >- Buy: the Arena instrument; side is the instrument's side. It must list on one live Kalshi market (409 no_tradable_listing otherwise). ticker: type: string description: >- Buy: a Kalshi market ticker instead of instrumentId; side is the market's side. Never echoed back while the venue-data switch is off. side: type: string enum: - 'yes' - 'no' description: 'Buy: the side to buy.' count: type: integer minimum: 1 maximum: 1000000000 description: 'Buy: contracts. Your paper balance is the limit.' tradeId: type: string format: uuid description: 'Sell: the open position (GET /portfolio).' limitPriceCents: type: integer minimum: 1 maximum: 99 description: 'Limit: your price for the side you trade, in cents (a percent).' timeInForce: type: string enum: - gtc - ioc - fok - good_till_canceled - immediate_or_cancel - fill_or_kill default: gtc expiresAt: type: string format: date-time description: 'gtc only: when the order stops resting. At most 365 days out.' maxPriceCents: type: integer minimum: 1 maximum: 99 description: >- Market buy: refuse to fill above this (409 price_moved, nothing placed). minPriceCents: type: integer minimum: 1 maximum: 99 description: >- Market sell: refuse to sell below this (409 price_moved, nothing sold). route: type: string enum: - kalshi - best description: >- best: a fill may be priced at Novig's or Polymarket's price when it passes every check. Omitted: Kalshi's. statedProbPct: type: integer minimum: 1 maximum: 99 description: >- Buy: your probability for the side. Never changes the fill; scored on /eval. Paper only. execution: type: string enum: - paper - kalshi - poly-intl default: paper description: >- paper (default) uses the paper book and trade:write. kalshi sends a live Kalshi order and needs trade:write:kalshi. poly-intl sends a live Polymarket International order and needs trade:write:poly-intl. Polymarket US is not a value. op: type: string enum: - create - cancel - amend description: Live only. Default create. orderId: type: string format: uuid description: 'Live cancel or amend: the Kalshi order id.' priceCents: type: integer minimum: 1 maximum: 99 description: 'Live: the price of the side, in cents.' updatedPriceCents: type: integer minimum: 1 maximum: 99 description: 'Live amend: the new price of the side.' updatedCount: type: integer minimum: 1 description: 'Live amend: the new contract count.' OrderResult: type: object required: - status - action - type - idempotencyKey - replayed - originalCreatedAt - order - trade - fillVenue - mode - venueData properties: status: type: string enum: - executed - resting - canceled description: 'canceled: an ioc or fok that did not fill. Nothing was spent.' action: type: string enum: - buy - sell type: type: string enum: - market - limit idempotencyKey: type: string format: uuid replayed: type: boolean description: >- True when this idempotencyKey was used before: the stored order, nothing new placed. originalCreatedAt: type: - string - 'null' format: date-time description: 'On a replay: when the order was first placed.' order: oneOf: - $ref: '#/components/schemas/OrderDetail' - type: 'null' description: >- The limit order. Null for a market order, which is a fill and not an order. trade: oneOf: - $ref: '#/components/schemas/Trade' - type: 'null' description: >- The position opened (buy) or closed (sell). Null while resting or canceled. fillVenue: type: - string - 'null' enum: - kalshi - novig - polymarket - null description: >- Where the fill was priced. Paper only: nothing is sent there. The first leg when the ticket split. fills: type: array description: >- Present when route best split one ticket across venues. priceCents is omitted while venue data is off. items: type: object required: - venue - contracts properties: venue: type: string enum: - kalshi - novig - polymarket contracts: type: number priceCents: type: integer minimum: 1 maximum: 99 mode: type: string const: paper venueData: type: boolean fillPriceCents: type: - integer - 'null' description: Only while the venue-data switch is on. organization: type: object description: >- Present when X-Arena-Org selected an organization sandbox. Absent on the personal account. required: - id properties: id: type: string format: uuid slug: type: - string - 'null' description: The organization's slug. Null when the sandbox did not name one. 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 - 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 - 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.' OrderDetail: allOf: - $ref: '#/components/schemas/Order' - type: object required: - type - cancelReason - tradeId properties: type: type: string const: limit cancelReason: type: - string - 'null' description: >- user, expired, not_filled, market_closed, market_resolved, position_closed, and so on. tradeId: type: - string - 'null' format: uuid description: The position it opened or closed, once executed. fillPriceCents: type: - integer - 'null' description: Only while the venue-data switch is on. Trade: allOf: - $ref: '#/components/schemas/Position' - type: object required: - status - closedAt - closeReason - pnlDollars - resolvedOutcome properties: status: type: - string - 'null' enum: - open - won - lost - settled_push - cancelled - sold - null closedAt: type: - string - 'null' format: date-time closeReason: type: - string - 'null' pnlDollars: type: - number - 'null' resolvedOutcome: type: - string - 'null' enum: - 'yes' - 'no' - push - void - null description: The instrument's result. Order: type: object required: - orderId - action - instrumentId - instrumentLabel - instrumentSide - orderSide - contracts - filledContracts - remainingContracts - limitCents - holdDollars - timeInForce - expiresAt - status - createdAt properties: orderId: type: string format: uuid action: type: - string - 'null' enum: - buy - sell - null instrumentId: type: - string - 'null' instrumentLabel: type: - string - 'null' instrumentSide: type: - string - 'null' enum: - 'yes' - 'no' - null orderSide: type: - string - 'null' enum: - 'yes' - 'no' - null contracts: type: integer filledContracts: type: integer remainingContracts: type: integer limitCents: type: - integer - 'null' description: Your own limit. holdDollars: type: number timeInForce: type: - string - 'null' expiresAt: type: - string - 'null' format: date-time status: type: - string - 'null' statedProbPct: type: - integer - 'null' placedVia: type: - string - 'null' placedPrivate: type: boolean createdAt: type: - string - 'null' format: date-time marketTicker: type: - string - 'null' description: Only while the venue-data switch is on. Position: type: object required: - tradeId - instrumentId - instrumentLabel - instrumentSide - boughtSide - contracts - costDollars - statedProbPct - placedVia - placedPrivate - parlayId - fillVenue - openedAt properties: tradeId: type: string format: uuid instrumentId: type: - string - 'null' description: The Arena instrument the market lists; null when not mapped. instrumentLabel: type: - string - 'null' description: The instrument's YES side in words. instrumentSide: type: - string - 'null' enum: - 'yes' - 'no' - null description: The side of the instrument held. boughtSide: type: - string - 'null' enum: - 'yes' - 'no' - null description: The side of the market bought. contracts: type: integer costDollars: type: number description: Paper dollars paid. statedProbPct: type: - integer - 'null' description: The probability you stated when placing, if any. placedVia: type: - string - 'null' placedPrivate: type: boolean parlayId: type: - string - 'null' format: uuid fillVenue: type: string openedAt: type: - string - 'null' format: date-time marketTicker: type: - string - 'null' description: Only while the venue-data switch is on. entryCents: type: - number - 'null' description: Only while the venue-data switch is on. headers: RateLimit-Limit: description: The plan's requests per minute (all keys of the account together). schema: type: integer 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 Arena-Quota-Reset: description: Seconds until 00:00 UTC on the 1st. schema: type: integer Arena-Plan: description: none (signed in, without a plan), basic, builder, desk or enterprise. schema: type: string X-Request-Id: description: Quote it when asking for help. schema: type: string Retry-After: description: Seconds to wait before trying again. schema: type: integer 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.