​

Browser and backend protocol

• Conventions
• Money encoding
• Authentication and CSRF
• Errors
• Health and status
• REST endpoints
• Trading
• WebSocket

​

Conventions

• Same origin. The browser talks only to the backend, never to a venue. In development the Vite dev server at http://localhost:5173 serves the app and proxies /api and /ws to the backend on 127.0.0.1:8080. In production the Go binary serves both. The backend sends no CORS headers.
• Field names are snake_case in JSON.
• Timestamps are RFC 3339 strings in UTC, e.g. "2026-09-30T03:12:40Z".
• IDs are namespaced strings: a venue prefix, a colon, then the venue’s id (Id schema, pattern ^[a-z]+:[A-Za-z0-9_.-]+$, at most 120 characters). For Polymarket (core/market.go):

  Object	Form	Example
  Market	pm:<conditionId>	pm:0xfe4a8a13fb0096ad21c70e189f9c69c4644d8022231ddb3017d527441db65547
  Outcome token	pm:<tokenId>	pm:99853173104990688338093880260846336068357323093533009368456412293249893123771
  Game	pm:<gameId>	pm:30025460

  Event, league, team and tag ids use the same prefix; their venue part is defined by implementation. Treat every id as an opaque string.
• Money, prices and sizes are decimal strings. See the next section.

​

Money encoding

• Market.line is a signed decimal string for a spread or total, e.g. "-3.5". It is a label, not money.
• Game.home_score and Game.away_score are free-form strings, because some sports report sets or maps ("7-6(7-2), 0-0").
• Counts (max_open_orders, price_band_ticks, seconds_delay, market_count, positions_count, open_orders, resting_orders) and the WebSocket seq are JSON integers.

​

Why there are no floats

• Binary floats cannot hold most decimal prices. 0.1, 0.47 and 0.53 have no exact float64 or JS number value, so 0.1 + 0.2 is 0.30000000000000004. A price that drifts by one unit in the last place no longer matches its book level or tick.
• A click sends exactly the price shown. Clicking a price sends a GTC limit order at that price (CLAUDE.md). If the displayed string came from a float it could differ from the level the backend holds.
• Signing must match byte for byte. Order amounts are derived from price and size with integer floor rounding and checked against golden vectors from the official SDK. Float rounding can differ from an integer floor at boundaries.
• Range. Micros is an int64. A JS number is exact only up to 2^53, about 9 × 10^15 micros (9 billion units); a string never loses precision.
• Tick checks must be exact. engine/risk checks that a price is a whole multiple of the tick size. That test is exact on integers and unreliable on floats.

​

Authentication and CSRF

1. POST /api/auth/login with {"password": "..."}. On success the backend sets the sesame_session cookie (HttpOnly, SameSite=Strict, Path=/, plus Secure behind TLS) and returns a Session:
   { "authenticated": true, "csrf_token": "<token>", "expires_at": "2026-09-30T15:00:00Z" }
   
2. GET /api/auth/session returns the same shape. It is public, so the app can call it on load to learn whether it is logged in and to get the CSRF token again after a reload. When logged out it returns {"authenticated": false}.
3. Every operation is authenticated unless the spec marks it security: []. The public operations are GET /health, POST /auth/login and GET /auth/session. A request without a valid session gets 401 unauthorized.
4. Every authenticated request that is not GET or HEAD must also send the X-CSRF-Token header with the session’s csrf_token. A missing or wrong token gets 403 csrf_invalid. The generated client adds the header in middleware.
5. POST /api/auth/logout is authenticated and needs the CSRF header. It deletes the session and clears the cookie.

​

Errors

{ "code": "csrf_invalid", "message": "missing or wrong X-CSRF-Token header" }

​

Health and status

• version: the backend build version.
• trading_enabled: true only when LIVE_TRADING is exactly true and the latest geoblock check succeeded and reported not blocked. The SAFE/ARMED switch is separate state, checked per order.
• geoblock: blocked, checked_at, and country, region and error when known. blocked is true before the first successful check and whenever the latest check failed (fail closed).
• feeds: one FeedStatus per venue feed: feed (e.g. pm.market, pm.sports), connected, last_message_at, and error when the feed is down.

​

Serving the web UI

​

REST endpoints

​

system

​

auth

​

settings

​

markets

• search serves the command palette from the local search index (catalog). q is required, 1–200 characters; limit is 1–50, default 20. Each SearchHit has a kind (event, market, team or league), an id, a title, and optionally subtitle, image, live, pinned, event_id and game_id. Ranking is defined by implementation, following PLAN §4.2 (pinned, then held, then live, then volume, inside text-match tiers).
• events pages with an opaque keyset cursor. Pass the previous page’s next_cursor; it is absent on the last page. limit is 1–100, default 50.
• history returns the price series of one outcome token (token_id) over interval: 1h, 6h, 1d, 1w, 1m or max. Each point is {"t": <time>, "p": <Decimal>}.

​

sports

• window is live (default), today or upcoming. Repeat league to filter by up to 50 league ids.
• The board is grouped by league. Each GameCard has the Game and its main markets in the order moneyline, main spread, main total, when present.
• The board gives the game state at the time of the request. Later changes arrive on game:<game_id>; prices arrive only on book:<token_id>.

​

watchlist

​

account

• account always answers 200, with or without credentials. AccountSummary has wallet_address (empty when not configured), credentials, positions_count and open_orders, and optionally cash with cash_updated_at, liquidation_value, cost_basis, unrealized_pnl and valuation_stale. cash is absent while it cannot be read. What open_orders holds while credentials are not ready is defined by implementation. Live updates arrive on the account topic.
• portfolio/positions: status is open (default), redeemable or closed. A redeemable position has resolved and is claimed on polymarket.com; the app never redeems. Each Position carries the venue’s size, avg_price, cost_basis and realized_pnl, and, for open positions, the valuation from engine/portfolio: best_bid, liquidation_value, liquidation_complete (false when the visible bids cannot absorb the whole position), unrealized_pnl, valuation_stale and resting_orders. Open positions also stream on the positions topic.
• portfolio/pnl: interval is 1d, 1w, 1m or all. Points are {"t": <time>, "pnl": <SignedDecimal>}, the cumulative P&L from the Data API.
• orders lists open orders, optionally for one market_id. It needs venue credentials. Updates stream on the orders topic.
• activity pages the account history (trades, redeems, merges, splits, rewards, conversions and transfers made on polymarket.com) with an opaque cursor; pass the previous page’s next_cursor. limit is 1–100, default 50. It is history only; live fills come from the fills topic.

​

Credentials

​

No prices in REST

​

Trading

​

Placing an order

• Idempotency. A repeated client_order_id returns the first result and sends nothing. A client that did not receive a response may resend the same request with the same client_order_id safely; it must never mint a new id for the same intent.
• unknown means the backend did not get the venue’s answer in time. It never re-sends the order; it reconciles from the venue’s open orders and trades, and the outcome arrives on the orders and fills topics. From Phase 4 the reconciled result also arrives on the placements topic as a PlaceOrderResponse with the same client_order_id. The client shows the order as pending until then.
• Reject codes are the RejectCode constants in core/trading.go: risk codes such as not_armed, price_band and max_order_notional, and venue codes prefixed venue_. They are listed under Reject codes. A client that meets an unknown code shows message.
• The browser sends the stake, not the size. A one-click order carries notional (the stake in pUSD) and the backend sets size = notional ÷ price, rounded down to 0.01 shares, records that size in the audit log and checks it against the tick, the minimum size and the limits before signing. size is sent instead only where the user chose a share count (exactly one of the two is set). Exit and Hedge send neither: the server sizes them.

​

Reject codes

​

Cancelling

• CancelOrdersRequest.order_ids holds 1 to 1000 venue order ids.
• CancelMarketRequest has a market_id and an optional token_id to cancel one outcome only.
• cancel-all has no body and cancels every open order of the account on the venue.
• Cancels work in SAFE, with LIVE_TRADING off and while geoblocked; the risk engine never blocks them.

​

Replacing an order

​

Exiting a position

• walk sells the whole position at the lowest bid level that fills it, no more than exit_slippage_ticks below the best bid.
• join rests a post-only sell for the whole position at the best ask.

​

Trading state and the switch

• ARMED is held in memory only. Every start is SAFE. The backend drops to SAFE on idle timeout, logout, a geoblock change, loss of credentials and foreign activity.
• POST /trading/arm returns 409 not_armable while reasons holds anything besides not_armed. POST /trading/safe always succeeds.
• A trading action extends armed_until; which requests count is defined by implementation.

​

Risk settings

• No limit may exceed its ceiling (400).
• Raising any limit, widening the band or the slippage, or turning off a safety setting needs password (the UI password) in the same request; without it the answer is 403 step_up_required. Lowering needs no password.
• A limit of 0 rejects every order it covers.

​

Alerts and notifications

• Alerts. CreateAlertRequest has alert_kind (price, spread, score, game_start, game_end), token_id for price and spread alerts or game_id for game alerts, cross_direction (above watches the best bid, below the best ask) and price on the market’s tick, and optional repeat and note (200 characters). An update can pause or resume an alert and change its price, direction, repeat and note.
• Notifications. Each Notification has an id, a notification_kind, a severity (info, warning, critical), a title and body, and when they apply a market_id, token_id, game_id, alert_id or client_order_id. The client_order_id of an order notification is the placement’s, so the tab that clicked can skip toasts it already showed. POST /notifications/read marks every notification up to and including up_to.
• Settings. NotificationSettings holds one rule per kind (in_app, desktop, sound, telegram), the sound_volume, and a read-only telegram_configured. in_app and telegram are always on for foreign_activity and credentials; a rule that turns them off is refused with 400. The browser applies the in-app, desktop and sound rules to what arrives on the notifications topic; the server applies the Telegram rule.
• Test. POST /notifications/test sends one notification of kind test to every channel, whatever the rules. It reaches the browser channels even when Telegram fails (502 telegram_error); without Telegram configured it succeeds without it.
• Telegram is outbound only and has no endpoint here: the server sends, and never receives updates. TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID are set together or not at all; without them telegram_configured is false and nothing goes to Telegram.

​

Combos

• Quote. A buy sends client_order_id, side: "buy", leg_token_ids (2 to 50 pm: outcome tokens) and notional (the stake, fees included). A sell (Exit) sends token_id (the pmc: combo position) and size. status is quoted, no_quote or rejected; rfq carries the quote with expires_in_ms, computed by the server when it sends the message. The browser counts down from that value from the moment the message arrives, never from its own clock against expires_at. A quote request works in Safe and is never repeated.
• Accept. The body is ids only: client_order_id, rfq_id, quote_id. status is accepted, rejected or unknown. An unknown Accept is settled by status reads and never re-sent; its final state arrives on the combo_rfqs topic with a combo_filled or combo_failed notification. 404 not_found is an rfq_id that is not one of this app’s recent quote requests.
• Business outcomes are 200, as for orders. The combo reject codes are listed in the Reject codes section.
• 503 combos_unavailable means no Combos venue is configured: the quote, accept and RFQ endpoints without a Session Key, the positions and activity endpoints without a wallet address. As a reject code or a combos_reasons entry, combos_unavailable means the credentials lack the combos scope.
• GET /trading carries combos_can_trade and combos_reasons; GET /account carries credentials.scopes (trading, combos) and combo_cost_basis.

​

WebSocket

​

Connecting

• One socket per browser tab, at GET /ws on the same origin as the app (ws:// in development through the Vite proxy, wss:// behind TLS). /ws is outside /api and is not an OpenAPI path; its messages are the Ws* schemas in the spec.
• Auth: the sesame_session cookie is checked at the upgrade exactly as for REST, including timeouts. No token goes in the URL or the first frame. An upgrade without a valid session is refused before the socket opens.
• Origin: the upgrade must carry an Origin header equal to the app’s configured public origin (plus the Vite dev origin in development). A missing or foreign Origin is refused with 403 before the upgrade. This stops another site from opening the socket with the user’s cookie.
• Sockets are receive-only for data. The client can only subscribe, unsubscribe and ping. Commands go over REST.
• The security checklist requires logout to close the session’s sockets. Whether an expired session closes an open socket immediately is defined by implementation.

​

Client messages

{ "op": "sub", "id": "c1", "topics": [
  "book:pm:99853173104990688338093880260846336068357323093533009368456412293249893123771",
  "game:pm:30025460",
  "feeds",
  "status"
] }

{ "op": "unsub", "id": "c2", "topics": ["game:pm:30025460"] }

{ "op": "ping", "id": "p17" }

​

Server messages

​

Topics

• book: a snapshot replaces the book. A delta lists changed levels as [price, size] pairs; each sets the size at that price, and size "0" removes the level. A delta can also carry tick_size, last_trade, stale and updated_at; apply each field present and keep the rest. Bids are sorted high to low and asks low to high in a snapshot; after applying a delta the client keeps that order.
• game: replace the stored Game with data.
• feeds: a snapshot replaces the list; a delta replaces the entry with the same feed name, or adds it.
• status: replace the stored Status with data.
• account: replace the stored AccountSummary with data.
• positions: a snapshot replaces the list of open positions. A delta replaces the position with the same token_id, or adds it; a delta with size "0" removes it. Valuation changes are coalesced to at most one delta per second per position.
• orders: a snapshot replaces the list of open orders. A delta replaces the order with the same id, or adds it. A delta whose status is terminal (matched, cancelled or unmatched) removes the order from the open list; live and delayed keep it. A delayed order cannot be cancelled until delay_ends_at, when the venue reports it.
• fills: a snapshot replaces the list with today’s fills. A delta adds a fill, or replaces the fill with the same id: a fill’s status moves from matched to mined to confirmed, and can pass through retrying or end in failed (the match was reverted). Whether every status step is sent, and where “today” starts, are defined by implementation.
• trading: replace the stored TradingState with data. The UI drives the SAFE/ARMED switch, the ARMED marker and the trade buttons’ enabled state from it, and still treats the server’s reply to each order as the answer. How often counters such as orders_last_minute produce a delta is defined by implementation.
• orders in Phase 3: an Order placed by this app carries its client_order_id, so the client can match a pending intent to its order. cancel_pending: true marks an order whose cancel is queued behind a sports delay window.

{ "type": "snapshot", "topic": "book:pm:99853173104990688338093880260846336068357323093533009368456412293249893123771", "seq": 1,
  "data": {
    "token_id": "pm:99853173104990688338093880260846336068357323093533009368456412293249893123771",
    "bids": [["0.46", "1520"], ["0.45", "3310.5"], ["0.44", "8000"]],
    "asks": [["0.47", "2131"], ["0.48", "905"], ["0.49", "12000"]],
    "tick_size": "0.01",
    "last_trade": { "price": "0.47", "size": "25", "side": "buy", "at": "2026-09-30T03:12:39Z" },
    "stale": false,
    "updated_at": "2026-09-30T03:12:40Z"
  } }

{ "type": "delta", "topic": "book:pm:99853173104990688338093880260846336068357323093533009368456412293249893123771", "seq": 2,
  "data": {
    "token_id": "pm:99853173104990688338093880260846336068357323093533009368456412293249893123771",
    "bids": [["0.46", "0"], ["0.42", "2131"]],
    "updated_at": "2026-09-30T03:12:40.424Z"
  } }

{ "type": "snapshot", "topic": "game:pm:30025460", "seq": 1,
  "data": {
    "id": "pm:30025460", "league_id": "pm:nhl",
    "home": { "id": "pm:edm", "name": "Edmonton Oilers", "abbreviation": "EDM" },
    "away": { "id": "pm:van", "name": "Vancouver Canucks", "abbreviation": "VAN" },
    "home_score": "2", "away_score": "1", "period": "P2", "clock": "17:36",
    "status": "InProgress", "live": true, "ended": false,
    "start_time": "2026-09-30T02:00:00Z",
    "event_ids": ["pm:nhl-van-edm-2026-09-29"],
    "updated_at": "2026-09-30T03:12:41Z"
  } }

{ "type": "snapshot", "topic": "feeds", "seq": 1,
  "data": { "feeds": [
    { "feed": "pm.market", "connected": true, "last_message_at": "2026-09-30T03:12:40Z" },
    { "feed": "pm.sports", "connected": true, "last_message_at": "2026-09-30T03:12:38Z" }
  ] } }

{ "type": "delta", "topic": "feeds", "seq": 2,
  "data": { "feed": "pm.market", "connected": false, "last_message_at": "2026-09-30T03:14:02Z", "error": "connection closed" } }

{ "type": "snapshot", "topic": "account", "seq": 1,
  "data": {
    "wallet_address": "0x<deposit wallet address>",
    "credentials": { "state": "ready", "signer_address": "0x<session key address>" },
    "cash": "412.5", "cash_updated_at": "2026-09-30T03:12:00Z",
    "liquidation_value": "92", "cost_basis": "90", "unrealized_pnl": "2",
    "valuation_stale": false, "positions_count": 1, "open_orders": 1
  } }

{ "type": "delta", "topic": "account", "seq": 2,
  "data": {
    "wallet_address": "0x<deposit wallet address>",
    "credentials": { "state": "failed", "signer_address": "0x<session key address>", "reason": "auth_rejected" },
    "positions_count": 1, "open_orders": 0
  } }

{ "type": "delta", "topic": "positions", "seq": 7,
  "data": {
    "token_id": "pm:99853173104990688338093880260846336068357323093533009368456412293249893123771",
    "market_id": "pm:0xfe4a8a13fb0096ad21c70e189f9c69c4644d8022231ddb3017d527441db65547",
    "outcome": "Canucks", "title": "Canucks vs. Oilers",
    "size": "200", "avg_price": "0.45", "cost_basis": "90", "realized_pnl": "0",
    "status": "open", "best_bid": "0.46",
    "liquidation_value": "92", "liquidation_complete": true,
    "unrealized_pnl": "2", "valuation_stale": false, "resting_orders": 1
  } }

{ "type": "delta", "topic": "orders", "seq": 4,
  "data": {
    "id": "0x<order hash>",
    "market_id": "pm:0xfe4a8a13fb0096ad21c70e189f9c69c4644d8022231ddb3017d527441db65547",
    "token_id": "pm:99853173104990688338093880260846336068357323093533009368456412293249893123771",
    "outcome": "Canucks", "side": "sell", "price": "0.55",
    "original_size": "100", "size_matched": "0",
    "status": "cancelled", "order_type": "GTC",
    "created_at": "2026-09-30T03:05:00Z", "updated_at": "2026-09-30T03:12:41Z"
  } }

{ "type": "delta", "topic": "fills", "seq": 3,
  "data": {
    "id": "<trade id>", "order_id": "0x<order hash>",
    "market_id": "pm:0xfe4a8a13fb0096ad21c70e189f9c69c4644d8022231ddb3017d527441db65547",
    "token_id": "pm:99853173104990688338093880260846336068357323093533009368456412293249893123771",
    "outcome": "Canucks", "side": "buy", "price": "0.45", "size": "200", "fee": "0",
    "role": "maker", "status": "confirmed", "at": "2026-09-30T02:58:12Z"
  } }

{ "type": "delta", "topic": "trading", "seq": 5,
  "data": {
    "armed": true, "can_trade": true, "reasons": [],
    "armed_until": "2026-09-30T03:40:00Z", "clock_skew_ms": 84,
    "daily_used": "12.5", "orders_last_minute": 1
  } }

{ "client_order_id": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b",
  "token_id": "pm:99853173104990688338093880260846336068357323093533009368456412293249893123771",
  "side": "buy", "price": "0.31", "size": "80.64", "order_type": "GTC" }

{ "client_order_id": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b", "status": "rejected",
  "reject": { "code": "price_band", "message": "<fixed text>" } }

{ "type": "ack", "id": "c1" }

{ "type": "error", "id": "c1", "topic": "book:bad",
  "error": { "code": "<defined by implementation>", "message": "<fixed text>" } }

{ "type": "pong", "id": "p17" }

​

Snapshot, deltas and seq

• The server answers a subscription with a snapshot of the topic, then sends delta messages as the topic changes.
• Every snapshot and delta carries seq. It increases by one per message per topic. The client stores the seq of each snapshot as the topic’s base and expects each following message on that topic to be exactly one higher.
• A gap means the client’s state for that topic is wrong. On a seq that is not the previous value plus one, the client drops its state for the topic, shows it as stale, and resubscribes that topic: unsub then sub. It ignores deltas for the topic until the new snapshot arrives. unsub then sub works whether or not a repeated sub on an already-subscribed topic sends a fresh snapshot, which is defined by implementation.
• Whether seq starts at 1 or continues after a resubscribe is defined by implementation. Always take the new snapshot’s seq as the base.
• A client may receive a snapshot on a topic it is already following, for example after the venue feed resyncs. It replaces the topic’s state with it, like the first snapshot.
• Deltas for a topic that has no snapshot yet are ignored.
• Updates are coalesced to about 10 per second per topic. A coalesced book delta holds the latest size of every level that changed in the window, so the rules above still apply. The exact rate is defined by implementation.

​

Ping and pong

• The client sends {"op": "ping", "id": ...}; the server answers {"type": "pong", "id": ...} with the same id. Browsers cannot see WebSocket protocol pings, so this is how the client measures latency and detects a dead socket. The interval and the timeout after which the client treats the socket as dead and reconnects are defined by implementation.
• The server also sends WebSocket protocol-level pings, which browsers answer automatically, and closes a socket that stops answering. The security checklist sets every 30 s with a drop after 2 missed pongs; the final values are defined by implementation.

​

Limits

​

Slow clients

​

Reconnecting

1. Mark every subscribed topic stale in the UI; keep showing the last values greyed out.
2. Reconnect with a backoff. The schedule and jitter are defined by implementation.
3. Resubscribe every topic the UI still needs, in sub messages of at most 500 topics.
4. Replace each topic’s state with its new snapshot and take its seq as the base. Nothing from the old socket carries over.

​

Stale books

• BookSnapshot.stale is true while the market feed is disconnected or resyncing that token. A BookDelta that carries only stale changes the flag and leaves the levels as they are.
• When the feed recovers, the backend resubscribes the token at the venue for a fresh book (never REST /book, PLAN §3.7) and sends the new state with stale: false. Whether that state arrives as a new snapshot or as deltas is defined by implementation; the rules above handle both.
• While a book is stale the UI greys its prices and disables clicking them. It never fills the gap from another source.
• The feeds topic reports each feed’s connected flag and last_message_at, which drive the feed status indicator. A game has no stale field; while pm.sports is disconnected, the UI shows game state from that feed as stale.
• The lag threshold after which a connected but silent feed counts as stale, and whether the backend or the client applies it, are defined by implementation.