REFERENCE
API reference
Every venue action the web app performs is a plain HTTP call. Sessions are cookie-scoped, so a client that keeps cookies keeps its account.
Endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /api/health | Venue heartbeat: TVL, trader count, mode. |
| GET | /api/state | Full venue snapshot plus the caller's session account. |
| GET | /api/markets | Listed markets, chain metadata, and the USDG quote asset. |
| GET | /api/quote?symbol&side&leverage&expiryHours&size | Indicative premium, strike, breakeven, and the payoff band. Read-only. |
| GET | /api/candles?symbol&range | OHLC series for the chart. Requires a reachable upstream feed. |
| POST | /api/trade { symbol, side, leverage, expiryHours, sizeUsd } | Open a position. Debits the premium and reserves the worst-case payout. |
| POST | /api/deposit { amount } | Add USDG to the vault, mint LP shares. |
| POST | /api/withdraw { amount } | Burn shares against free liquidity only. |
| POST | /api/claim { positionId } | Collect a settled winning position. |
| POST | /api/faucet | Session-scoped test USDG. Ledger mode only. |
| POST | /api/wallet { address } | Bind a connected wallet to the session. |
| GET | /api/oracle/publish | Protected publisher — pushes quotes on-chain. Requires the CRON_SECRET bearer token. |
Sessions
The first request that touches /api/state issues a session cookie. Every balance, position, and point total is keyed to it. Calling POST /api/wallet binds a connected address to the same session so the ledger and the wallet agree on who you are.
Limits
| Rate limit | 1 write / 200 ms per session Writes inside the window return “Slow down”. |
| Sessions retained | 500 Oldest sessions are evicted once the cap is reached. |
| Quote cache | 30 s Upstream market data is refetched at most twice a minute. |
| Quote max age | 15 min Older prints stop counting as live and the venue degrades to a simulated series. |
The ledger endpoints move session balances, not tokens. Once the vault and engine addresses are configured, value-moving actions are wallet-signed transactions and the contract — not this API — is authoritative.
Example
Price a 24-hour 5× UP option on NVDA for 500 USDG:
curl -s "http://localhost:3000/api/quote\ ?symbol=NVDA&side=UP&leverage=5&expiryHours=24&size=500"