API Reference

REST Sketch

This page separates implemented pulse-server routes from target execution routes. The alpha terminal and paper routes below exist in the Go pulse server. Production order, settlement, and redemption routes are target contracts unless called out as implemented by a specific page or release note.

GET  /api/status
GET  /api/stats
GET  /api/events
GET  /api/events/sports
GET  /api/events/{id}

GET  /api/markets
GET  /api/markets/{marketId}

POST /api/alpha/polymarket/markets/map
GET  /api/alpha/markets/{marketId}/insights/rules
POST /api/alpha/markets/{marketId}/paper-mirror
GET  /api/alpha/markets/{marketId}/brief/preview
POST /api/alpha/markets/{marketId}/briefs
GET  /api/alpha/briefs/{briefId}
POST /api/alpha/markets/{marketId}/decision-notes
GET  /api/alpha/markets/{marketId}/decision-notes
POST /api/alpha/decision-notes/{noteId}/review
GET  /api/alpha/markets/{marketId}/wallet-radar
GET  /api/alpha/wallets/{address}
PUT  /api/alpha/wallets/{address}/tag

POST /api/paper/faucet/claim
GET  /api/paper/status
GET  /api/paper/markets
GET  /api/paper/markets/{marketId}
GET  /api/paper/markets/{marketId}/book
GET  /api/paper/markets/{marketId}/trades
GET  /api/paper/markets/{marketId}/rules
GET  /api/paper/accounts/{address}/portfolio
GET  /api/paper/accounts/{address}/positions
GET  /api/paper/accounts/{address}/fills
POST /api/paper/orders
POST /api/paper/orders/{orderId}/cancel
POST /api/paper/settlement/run
POST /api/paper/markets/{marketId}/live-events/simulate
POST /api/paper/markets/{marketId}/close
POST /api/paper/markets/{marketId}/resolve
POST /api/paper/markets/{marketId}/resolution/finalize
POST /api/paper/markets/{marketId}/redeem
GET  /api/paper/users/{userId}/wallets
POST /api/paper/users/{userId}/wallets
GET  /api/paper/users/{userId}/retention
POST /api/paper/wallets/{walletId}/refresh
GET  /api/paper/wallets/{walletId}/portfolio
GET  /api/paper/ws

GET  /api/comments
POST /api/comments
GET  /api/comments/nonce
POST /api/comments/{commentId}/report

GET  /api/auth/nonce
POST /api/auth/login
GET  /api/auth/me

Target execution routes:

GET  /api/markets/{marketId}/book
GET  /api/markets/{marketId}/trades
GET  /api/markets/{marketId}/rules
POST /api/orders
POST /api/orders/{orderId}/cancel
POST /api/orders/cancel-all
GET  /api/accounts/{address}/portfolio
GET  /api/accounts/{address}/orders
GET  /api/accounts/{address}/trades
GET  /api/accounts/{address}/redeemable
GET  /api/markets/{marketId}/redemption
GET  /api/contract-registry
GET  /api/paper/contract-registry

The registry routes above are target public client surfaces. The current pulse server has exchange registry config loading and validation, but does not expose those registry URLs in the route table yet.

WebSocket Sketch

WS /ws

market:{marketId}:book
market:{marketId}:trades
market:{marketId}:status
market:{marketId}:live-state
paper:status
account:{address}:orders
account:{address}:fills
account:{address}:portfolio

Paper WebSocket events use concrete event names while the production channel contract is still maturing:

paper_market_book
paper_matched_pending_fill
paper_settlement_confirmed
paper_account_positions
paper_market_lifecycle
paper_redemption_confirmed
paper_market_live_state
paper_status

Settlement And Portfolio Semantics

• matchedPending fills are not confirmed Outcome Shares.
• Settlement confirmation is required before portfolio positions appear.
• Primary binary matching creates YES/NO Outcome Shares through CTF Collateral splitting.
• Secondary resale transfers existing Outcome Shares.
• Redeemable Markets appear only after final resolution.
• Redemption APIs must prepare direct CTF redemption data, not a claim against an Arenaton balance.

Public Market Data

Public APIs should expose market list/detail, best bid/ask, recent trades, volume, open interest, resolution source, market status, and selected WebSocket updates.

Private account APIs require authentication and must enforce geo/risk restrictions for trading actions.

Market Brief Semantics

Market Brief APIs expose a free preview before any credit-consuming full run. The current pulse implementation supports a daily free full-run allowance and stores failed runs without consuming quota. Paid fallback is explicit: the request must confirm paid fallback before another full brief can use paid credits after free quota is exhausted.

A full brief may consume free-run allowance or paid credits only after the quality gate confirms the required sections, timestamped sources, price context, rules context, Watch/Risk/Avoid/Rehearse fields, generated-at timestamp, and visible source list. If the provider is unavailable or the output fails validation, the response degrades to a stored failed artifact or preview state without charging.

Brief output is decision support. It must not contain financial advice, buy/sell instructions, expected-return claims, confidence scores, fair-value models, edge ratings, or official resolution claims.

Freshness is recomputed when a stored brief is opened. The current implementation marks a brief Stale after a 4-cent YES price move, Review Needed when tracked lineup or injury timestamps change, Watch when the brief ages near tip-off, and Stale when the mapped market is closed, suspended, or resolved.

External CTF Market Data

Arenaton can consume public third-party CTF market data for browsing and research surfaces. External market-data APIs must not become Arenaton order intake, settlement authority, or registry configuration.

GET  /markets              — List all active CTF markets (up to 500)
GET  /market?condition_id= — Single market details
GET  /book?token_id=       — Order book for a token
POST /prices               — Batch prices for up to 500 token IDs

WS wss://ws-subscriptions-clob.polymarket.com/ws/market

Third-party contract addresses are references only. Arenaton clients must read live addresses from /api/contract-registry or /api/paper/contract-registry. See Gnosis CTF Model for the contract-boundary rules.

Compatibility Routes

The pulse server still exposes compatibility routes for current health checks, event data, and GraphQL probes while the exchange API matures.