Rizon
A paper-money exchange: read live order books, place practice trades and test a bot. No sign-up.
Documentation
Rizon API
Trade Rizon from code: every market (Bitcoin, gold, the midterms, the Fed, dates like the next US strike on Iran, uptime and more), live prices and forecasts, the books, every trade on the exchange and your own account, over REST and a WebSocket. It's paper money: every account starts with $1,000 and can refill, so there's no sandbox. The real exchange is safe to build against.
| REST | https://rizon.markets/api/v1 |
|---|---|
| WebSocket | wss://rizon.markets/api/v1/ws |
| Auth | Authorization: Bearer rz_… (market data needs no key) |
| Format | JSON. Money in paper USD, times in milliseconds since 1970 (server clock), strikes on each market's grid |
| For AI agents | CLAUDE.md · llms.txt · this page as Markdown |
Quickstart
# Market data needs no key
curl https://rizon.markets/api/v1/markets
# A key: make one at https://rizon.markets/docs#keys, or have a script make an account and its key
curl -X POST https://rizon.markets/api/v1/accounts
export RIZON_API_KEY=rz_…
# Buy up, $10, on the 15-second market
curl -X POST https://rizon.markets/api/v1/orders \
-H "Authorization: Bearer $RIZON_API_KEY" -H "Content-Type: application/json" \
-d '{"market": "BTC-15s", "side": "up", "size": 10}'
The same in Python and TypeScript:
import os, requests
API = "https://rizon.markets/api/v1"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['RIZON_API_KEY']}"
print(s.get(f"{API}/markets").json()["markets"][0])
r = s.post(f"{API}/orders", json={"market": "BTC-15s", "side": "up", "size": 10})
print(r.status_code, r.json())
const API = 'https://rizon.markets/api/v1';
const headers = { Authorization: \`Bearer ${process.env.RIZON_API_KEY}\`, 'Content-Type': 'application/json' };
const { markets } = await (await fetch(\`${API}/markets\`)).json();
const res = await fetch(\`${API}/orders\`, { method: 'POST', headers, body: JSON.stringify({ market: 'BTC-15s', side: 'up', size: 10 }) });
console.log(res.status, await res.json());
Markets and contracts
A market is an underlying and a horizon, with one continuous book whose price is the strike, like a futures book: up is buy, down is sell. GET /markets lists every market there is, with its status. Every position pays a fixed 2× and its strike comes from the book, so every market trades at 50/50 and the book's midpoint is the forecast. There are three kinds:
kind | A position expires | Markets |
|---|---|---|
rolling | horizon seconds after its own fill, on a whole second (an uptime's on the first UTC midnight at or after that: its slot is a day) | BTC-15s, BTC-1m, BTC-5m; GOLD-15s, GOLD-1m, GOLD-5m; CLAUDE-UP-1d, CLAUDE-UP-7d, CLAUDE-UP-30d; POLY-UP-1d, POLY-UP-7d, POLY-UP-30d; ELON-1d, ELON-7d |
fixed | at the market's expiresAt, all at once, and it settles when the market resolves (often sooner) | HOUSE-R-2026 SENATE-R-2026 HOUSE-VOTE-2026 ANTH-IPO-CAP FED-2027 UST10Y-MAX-2026 PREDICT-FDV |
date | 2 days after its strike's midnight, sooner if the market resolves first: see Date markets | IRAN-STRIKE ANTH-IPO-DATE FABLE-NEXT |
Orders carry no expiry. Each fill is a trade on the public tape, and a position for each trader on it: their side, at the resting order's strike. Read the position's expiresAt rather than computing it: an order from the app can move a rolling one by a second. On a rolling market the expiry moves on every second, so a position can't be closed: it runs to expiry, and you hedge it with a later one. An up and a down at the same strike and expiry are flat.
up | wins if the underlying at expiry is above the strike |
|---|---|
down | wins if it's below the strike |
| Equal | a push: both sides get their size back |
| Payout | you pay your size; a win pays 2 × size, a loss pays 0. No fees |
| Size | $1 to $100,000 per order, at most 2 decimals |
Each market's rules (in GET /markets) say exactly what its number is, when and where it's read, and what happens when the source is late or the event doesn't come: they're the contract. In short:
| Underlying | The number | Strikes (strikeStep, strikeOffset) | Settlement |
|---|---|---|---|
BTC-USD | the Bitcoin price, in dollars: Coinbase, with Kraken as backup. If both are down the chart shows a simulated price and live is false: it's display-only, so new orders get 503 no price yet (resting ones stay) and it never settles a position | whole dollars (1, 0) | the last live price at or before the expiry, within about 50 ms of it. With no live price in the 5 s before (or only a simulated one), a push (settlePrice: null) |
PAXG-USD | gold, in dollars per troy ounce, as Paxos Gold (one token is an ounce; it tracks spot within about 0.2%): the median of the Coinbase and Kraken PAXG midpoints, to the cent, leaving out one with nothing fresh for 10 s, recomputed four times a second and ticked at least once a second. It trades around the clock | $0.10 (0.1, 0) | like BTC: the last price at or before the expiry; with none in the 5 s before, a push. No new orders without a price in the last 5 s (503 no price yet) |
HOUSE-R-2026 | House seats Republicans win in the Nov 3, 2026 midterms (runoffs and caucusing independents included) | half seats (1, 0.5), 0 to 435 | resolved by Rizon from official results and AP race calls, once every seat is decided; it halts trading when the last race is called |
SENATE-R-2026 | Senate seats Republicans hold in the 120th Congress | half seats (1, 0.5), 0 to 100 | the same |
HOUSE-VOTE-2026 | the national House vote margin, Democratic % minus Republican %, in points to one decimal (unit margin: 9.3 is D+9.3, −2.1 is R+2.1) | 0.1 points on x.x5 (0.1, 0.05), −100 to 100 | resolved by Rizon from the Clerk of the House's statistics |
IRAN-STRIKE | the UTC day of the next qualifying US strike on Iran (Polymarket's definition), as a JDN; Dec 31, 2026 if none | midnights (1, 0.5) | resolved by Rizon from a consensus of credible reporting |
ANTH-IPO-DATE | the first day (US Eastern) Anthropic's shares trade, as a JDN; Dec 31, 2026 if none | midnights (1, 0.5) | resolved by Rizon from the listing and SEC filings |
ANTH-IPO-CAP | Anthropic's market cap at the close of its first trading day, in billions of dollars (unit usdbn: 1,930 is $1.93T) | $10B (10, 0) | resolved by Rizon from the official close and the final prospectus; void if no IPO by the end of 2027 |
FABLE-NEXT | the day (US Eastern) a Claude Fable model of version 5.2 or higher is public, as a JDN; Dec 31, 2026 if none | midnights (1, 0.5) | resolved by Rizon from Anthropic's announcements |
FED-2027 | the federal funds target's upper bound in effect on Dec 31, 2027, in percent | between quarter points (0.25, 0.125), 0 to 20 | automatically, from FRED's DFEDTARU once it has Dec 31, 2027 |
UST10Y-MAX-2026 | the highest 10-year Treasury par yield close from Oct 29 through Dec 31, 2026, in percent | between basis points (0.01, 0.005), 0 to 20 | automatically, from the Treasury's daily par yield curve (FRED's DGS10 as backup) once Dec 31 is in |
PREDICT-FDV | predict.fun's PREDICT token's fully diluted value at 4:00 PM ET the day after it launches, in billions of dollars | $0.01B (0.01, 0) | resolved by Rizon from its most liquid spot market; void if no token by the end of 2027 |
CLAUDE-UPTIME-1D, CLAUDE-UPTIME-7D, CLAUDE-UPTIME-30D (one line per horizon: CLAUDE-UP-1d, -7d, -30d) | claude.ai's uptime over the 1, 7 or 30 whole UTC days before a position's expiry, in percent to two decimals: 100 × (1 − (major + 0.3 × partial outage seconds) ÷ the window's seconds). Each whole day counts as status.claude.com publishes it (its uptime bar), a day it hasn't as Rizon recorded it (the incident history, and a reading every minute). Between midnights the line is the live estimate, the window ending now | between hundredths (0.01, 0.005), 0 to 100 | a position expires at the first UTC midnight at least its horizon after its fill, and settles 1 hour later on its window's days; with no record of a day within 24 hours, a push. The 1-day books are often one-sided: most days are 100% |
POLYMARKET-UPTIME-1D, -7D, -30D (POLY-UP-1d, -7d, -30d) | the same for Polymarket's trading API (the CLOB), from status.polymarket.com's outage record | between hundredths (0.01, 0.005), 0 to 100 | the same |
ELON-POSTS | Elon Musk's posts on X since 2026-01-01 00:00 UTC, as Polymarket's XTracker counts them (main-feed posts, quotes and reposts, not replies): XTracker's running total less 2,618, its total at the start of the year. Read every 10 s, each new post stepping the count when XTracker recorded it. live is false after a minute without a read; no new orders after 2 minutes without one | half posts, like 11,520.5 (1, 0.5): a count never lands on one, so ELON never pushes | the count at the expiry, once the counter has been read at or after it (within about 10 s). With no read for 10 minutes, a push |
Status: open, closed, halted, resolved
status | Means |
|---|---|
open | it takes orders |
closed | past closesAt (a fixed market), or from 00:00 UTC on a date market's deadline day. Resting orders were canceled and refunded; positions wait for the value (a date market's still settle at their own expiry: see Date markets) |
halted | Rizon has paused it, say once an election's last race is called or an IPO's first session closes: new orders get 409 that market is halted; resting orders stay, and you can cancel them |
resolved | its value is in value, and every open position settled on it at once, whenever it came (before expiresAt too); resting orders were canceled and refunded. A market resolved with value null was voided: every position was refunded (result: push) |
A fixed market settles only on its resolution, never by the clock: past expiresAt without one, its positions wait. UST10Y-MAX-2026, FED-2027, and anything else whose source a machine can read are resolved automatically once the value is final by their rules; the others are resolved by Rizon from the source their rules name. Rolling markets never resolve: each position settles on its feed.
Date markets
The number is a day, as a Julian Day Number (JDN): an integer names a UTC day (2,461,343 is Oct 29, 2026). Strikes sit on.5, the midnight between two days: 2,461,359.5 is 2026-11-15 00:00 UTC, so Higher at it means "on Nov 15 or later, or not by the deadline", Lower means "by Nov 14", and a date never lands on a strike. A market takes strikes from the midnight that ends today (strikeMin) to the one that starts its deadline day (strikeMax); at each 00:00 UTC the strike that just passed leaves the book, and resting orders at it are canceled and refunded.
A position at strike k expires 2 days after k's midnight. If the market resolves before then, it settles on the reported day; if not, Higher wins, at settlePrice ceil(k), the day that starts at k's midnight. If the event hasn't happened by the deadline, the number is the deadline's day, and Higher wins at every strike.
const jdn = (date) => Math.floor(Date.parse(date) / 86_400_000) + 2_440_588; // '2026-11-15' → 2461360
const day = (jd) => new Date((jd - 2_440_587.5) * 86_400_000).toISOString().slice(0, 10); // 2461359.5 → '2026-11-15'
A worked example. On Oct 29, 2026 (JDN 2,461,343) the book for IRAN-STRIKE has its midpoint near 2,461,364: the market's forecast for the next US strike on Iran is Nov 19. If you think the ceasefire holds longer, buy Higher at the midnight that starts Nov 20, 2,461,364.5: {"market": "IRAN-STRIKE", "side": "up", "size": 10, "strike": 2461364.5}. Your position expires at Nov 22 00:00 UTC (expiresAt). If a strike on Nov 18 is reported first, every open position settles on 2,461,363 and yours loses; if none has been reported by then, it wins at 2,461,365.
Lines without a feed
A fixed or date market has no live feed: its line is its book's own midpoint, (best bid + best ask) / 2, the strike the book prices at 50/50. spot is the latest midpoint (kept while the book is one-sided; null before it was ever two-sided), and a position records it at its fill. price:<underlying> streams it at most once a second when it changes, and GET /prices/<underlying> keeps 90 days of it. On these markets, and on the uptimes, sigma is the line's realised move over the time left (from its hourly moves over the last week), or a typical scale for the market until the line has a day of history.
| Up order (buy) | Down order (sell) | |
|---|---|---|
| Book side | bid | ask |
| A limit at strike K trades at | any strike ≤ K | any strike ≥ K |
| Best | highest strike | lowest strike |
| A market order fills at | the best ask, then up the book | the best bid, then down the book |
A large market order can open several positions at several strikes. An order that would trade with your own resting order cancels that resting order instead (refunding it) and carries on down the book; the reply lists what it canceled.
There's no house. Every trade has an account on each side, and every account that has traded is on the leaderboard, people and bots alike. One of the bots is Rizon's market maker, which quotes every book so there's always something to trade. It's an ordinary account trading through this API, with the same rate limits as yours; its paper balance is larger, so it can quote every book. On BTC its best bid and ask are usually 1 strike apart at 15 s, 2 at 1 m and 4 at 5 m, wider while volatility runs high, centred on spot, with ten levels of $1,000 a side. On an event market it quotes around the median of the analogous Polymarket (or Kalshi) markets' prices, and on an uptime around the status page's own history; its source code is public. Rizon also runs a few taker bots that send small random market orders on every market, so the tape is never empty; they keep the default TRADER-#### names. One more, SHARP-BOT, takes any Bitcoin or gold quote a price move has left stale, so a slow quote costs you here as it would anywhere; its code is public too.
It re-quotes when the price moves, with one batch: its quotes that moved are canceled and replaced. Its new quotes trade with any resting order they cross, at that order's strike, so a resting order near the top of the book tends to fill right after the price moves through it. It hears prices on the same stream as everyone (every 50 ms; books every 100 ms), but it runs next to the exchange, so it hears them, and re-quotes, a little sooner than a client over the internet. Its replacement quotes join the back of each level's queue, so your order already resting at one of its strikes is ahead of it for other traders' market orders.
Keys
| Way | For | How |
|---|---|---|
| In the browser | you | Create key, on the docs page. It's shown once |
| Connect | an agent, on your account | POST /connect, then you approve one link |
| A new account | a script with nobody to approve | POST /accounts: an account and its key in one call |
Keys have a scope. trade (the default) trades, cancels and chats as you; read can only GET and stream. Your keys and callsign stay with you: on your own account only the browser manages them, so revoking a key you gave an agent really cuts it off. On an account an agent made with POST /accounts, which has no browser, its trade keys manage both. Send the key as Authorization: Bearer rz_…; only a browser's WebSocket, which can't set headers, passes ?key=rz_… instead. A key works until you revoke it.
Connect an agent
The agent asks; you approve in a browser where you trade on Rizon; the agent collects the key.
curl -X POST https://rizon.markets/api/v1/connect \
-H "Content-Type: application/json" -d '{"name": "btc-mm", "scope": "trade"}'
{
"code": "KX4P-9QHT",
"url": "https://rizon.markets/connect?code=KX4P-9QHT",
"poll": "https://rizon.markets/api/v1/connect/cr_8f…?wait=25",
"expiresAt": 1793309400000
}
Show the user url and code. Then GET poll (that's GET /connect/:id?wait=25) until status isn't pending: each call waits up to 25 seconds for an answer.
status | Means |
|---|---|
pending | not answered yet: poll again |
approved | key and account are in this response. The same poll gets it again for a minute, in case an answer is lost |
claimed | the key was handed over and that minute has passed: if you lost it, start again |
denied | the user said no |
expired | 10 minutes passed: start again |
name (1-40 characters, default "my agent") becomes the key's name in the user's list; scope defaults to trade. 30 requests per hour per address. The approval page itself uses GET /connect/codes/:code (what's being asked) and POST /connect/codes/:code with {"approve": true | false}, which returns {status}: approving takes a browser signed in to Rizon, denying only the code.
A new account
curl -X POST https://rizon.markets/api/v1/accounts \
-H "Content-Type: application/json" -d '{"name": "my_bot", "keyName": "v1"}'
Returns 201 {"key": "rz_…", "account": {…}}: a new account with $1,000 paper and a trade key that manages it. Both fields are optional: name is a callsign (3-16 letters, digits, _ or -; without one it's TRADER-####), keyName names the key (1-40 characters). 20 per hour per address.
Managing keys
| Method | Path | Does |
|---|---|---|
GET | /keys | {keys}: your live keys, without their secrets |
POST | /keys | {"name"?, "scope"?}: a new key, returned once with its secret in key |
DELETE | /keys/:id | Revokes it at once and closes its WebSockets. Returns the key |
These need the browser, or a trade key on an account made with POST /accounts. An account holds up to 20 live keys.
REST
Every path below is under https://rizon.markets/api/v1. Single objects come back as themselves, and lists in a field named for what they hold. Fields and parameters an endpoint doesn't take are refused, so a typo gets a 400 instead of being ignored. Lists page with limit (1-200, default 50) and cursor: pass back next from the previous page; it's null on the last.
Market data
No key needed.
| Method | Path | Returns |
|---|---|---|
GET | / | Links, the rules and every endpoint |
GET | /markets | {t, markets}: each market's spot, feed state and top of book |
GET | /books/:market | The book: up to 30 levels a side, and mid, (best bid + best ask) / 2 (null while one-sided) |
GET | /prices/:underlying?from=&to=&step= | {from, to, step, prices: [[t, price], …]} for an underlying (BTC-USD, PAXG-USD, a book-priced line like HOUSE-R-2026, an uptime like CLAUDE-UPTIME-7D, or ELON-POSTS, the count): the last value in each step ms (250 to 60,000; default 250), at most 20,000 of them: a longer span comes back at a coarser step, which the response's step gives. Default the last 10 minutes; a line that moves in steps (an uptime, a midpoint) starts with the value in force at from. The server keeps 20 minutes of BTC and of gold, five horizons and a day of an uptime (6, 36 or 151 days), 90 days of a book-priced line, and 30 days of ELON |
GET | /trades?market=&limit=&cursor= | {trades, next}: every trade on the exchange, newest first |
GET | /trades/:id | One trade |
GET | /leaderboard?limit= | {traders}: ranked by realised PnL (limit 1-100, default 20) |
GET | /traders/:id | One trader's record |
GET | /chat?limit=&room= | {messages}: the global chat's latest messages, oldest first (limit 1-50, default 50), or with room (an underlying, like BTC-USD; the uptimes share a room per page, CLAUDE-UPTIME, which a line's id like CLAUDE-UPTIME-7D also names) that market's room's, its last 30 at most |
GET /markets:
{
"t": 1793308800123,
"markets": [
{
"id": "BTC-15s", "underlying": "BTC-USD", "horizon": 15, "strikeStep": 1, "strikeOffset": 0, "spot": 114233.2, "live": true,
"bid": 114232, "ask": 114234, "bidSize": 1000, "askSize": 1000, "sigma": 35.45,
"kind": "rolling", "expiresAt": null, "deadline": null, "closesAt": null, "status": "open", "value": null, "unit": "usd",
"name": "Bitcoin", "category": "Crypto", "question": "Where will Bitcoin be?",
"rules": ["Higher wins if the BTC-USD price at expiry is above the strike; Lower wins if it is below.", …],
"strikeMin": null, "strikeMax": null
},
{ "id": "BTC-1m", "underlying": "BTC-USD", "horizon": 60, "strikeStep": 1, "strikeOffset": 0, "spot": 114233.2, "live": true, "bid": 114231, "ask": 114235, "bidSize": 1000, "askSize": 1000, "sigma": 70.9, "kind": "rolling", … },
{ "id": "BTC-5m", "underlying": "BTC-USD", "horizon": 300, "strikeStep": 1, "strikeOffset": 0, "spot": 114233.2, "live": true, "bid": 114229, "ask": 114238, "bidSize": 1000, "askSize": 1000, "sigma": 158.55, "kind": "rolling", … }
]
}
A fixed market, like the House:
{
"id": "HOUSE-R-2026", "underlying": "HOUSE-R-2026", "horizon": null, "strikeStep": 1, "strikeOffset": 0.5, "spot": 196.5, "live": true,
"bid": 195.5, "ask": 197.5, "bidSize": 500, "askSize": 500, "sigma": 8,
"kind": "fixed", "expiresAt": 1799125140000, "deadline": null, "closesAt": 1799125140000, "status": "open", "value": null, "unit": "seats",
"name": "House seats: Republicans", "category": "Politics", "question": "How many House seats will Republicans win in the 2026 midterms?",
"rules": ["The number is how many House seats Republicans win in the Nov 3, 2026 elections for the 120th Congress, …", …],
"strikeMin": 0.5, "strikeMax": 434.5
}
A date market: { "id": "IRAN-STRIKE", "underlying": "IRAN-STRIKE", "horizon": null, "strikeStep": 1, "strikeOffset": 0.5, "spot": 2461364, "kind": "date", "expiresAt": null, "deadline": 1798675200000, "closesAt": 1798675200000, "unit": "date", "strikeMin": 2461343.5, "strikeMax": 2461405.5, … }.
The ELON markets follow, like { "id": "ELON-1d", "underlying": "ELON-POSTS", "horizon": 86400, "strikeStep": 1, "strikeOffset": 0.5, "spot": 11540, … }.
horizon is in seconds (null on a market that isn't rolling). Strikes are strikeOffset plus a whole number of strikeStep s, from strikeMin to strikeMax where a market is bounded (a date market's move on every midnight). bid is the best up order (a market down order fills there), ask the best down order (a market up order fills there). spot is the underlying's latest value: a feed's, or on a market without one its book's latest midpoint. sigma is realised volatility: the underlying's one-sigma move over the horizon (to its expiry, on a fixed or date market), from its recent ticks, in its own units. Nobody quotes it.
Each market also says what it is: kind (rolling, fixed or date), status (open, closed, halted or resolved), value (what it resolved to; null until then, and on a voided market), unit (how its value is written: usd, count, seats, pct, margin (Democratic minus Republican points), date (a JDN), usdbn (billions of dollars) or uptime (percent)), name, category, question, and its rules in plain sentences. expiresAt is set on a fixed market, deadline (00:00 UTC on its last day) on a date one, closesAt (when trading stops) on both; all three are null on a rolling market. slot is the grid a rolling market's expiries sit on, in seconds: 1 (a whole second), or 86,400 on the uptimes (a UTC midnight); null on the others.
GET /books/BTC-15s:
{
"market": "BTC-15s",
"t": 1793308800123,
"bids": [{ "strike": 114232, "size": 1000 }, { "strike": 114230, "size": 1000 }],
"asks": [{ "strike": 114234, "size": 1000 }, { "strike": 114236, "size": 1000 }]
}
A trade: up and down are who is on each side, taker is the side whose order arrived and traded (the other was resting; when the market maker re-quotes through a resting order, it's the taker), and outcome is the side that won, or push, once it settles. A side is null only on trades from before 2026-10-28, when the exchange made its own market.
{
"id": "Xq3vT9aLm2Pk",
"market": "BTC-15s",
"strike": 114234,
"size": 100,
"spot": 114233.2,
"openedAt": 1793308800105,
"expiresAt": 1793308816000,
"up": { "id": "a1B2c3D4e5F6", "name": "TRADER-4821" },
"down": { "id": "Mk7p2Qa9Lr4X", "name": "TRADER-7215" },
"taker": "up",
"settlePrice": 114240.02,
"outcome": "up"
}
Your account
Any key, except to rename.
| Method | Path | Returns |
|---|---|---|
GET | /me | Your account |
GET | /orders?status=open|all&market=&limit=&cursor= | {orders, next}: open ones by default, newest first. Canceled orders that never filled are kept for a day |
GET | /orders/:id | One of your orders |
GET | /positions?status=open|settled|all&market=&limit=&cursor= | {positions, next}: open ones by default, latest expiry first |
GET | /positions/:id | One of your positions: your side of the trade with the same id |
GET | /exposure | {exposure}: your open positions summed by expiry and strike |
PATCH | /me | {"name"}: a new callsign (3-16 letters, digits, _ or -, unique). Your account. Only the account's owner: the browser, or a trade key on an account made with POST /accounts |
GET /me: your trader record, plus where your paper is. balance is free to trade, inOrders is held by your resting orders, inPositions is in open positions at cost. pnl is realised, and rank is null until your first position settles.
{
"id": "a1B2c3D4e5F6",
"name": "TRADER-4821",
"avatar": null,
"rank": 41,
"pnl": 0.5,
"wins": 6,
"losses": 5,
"pushes": 1,
"streak": 2,
"bestStreak": 3,
"balance": 870.5,
"inOrders": 100,
"inPositions": 30,
"equity": 1000.5
}
GET /exposure: one entry per underlying and second at which you hold open positions, soonest first, with your open size on each side at each strike. The underlying's value at that second settles them all, whichever of its markets they came from. At a settle price S, an up at strike k pays 2 × size if S > k, and a down pays 2 × size if S < k, so each entry gives your payout at every price. To keep exposure live, track your positions by id instead: hello (or GET /positions) has your open ones, and each position event updates one.
{
"exposure": [
{ "underlying": "BTC-USD", "expiresAt": 1793308816000, "strikes": [{ "strike": 114232, "up": 0, "down": 50 }, { "strike": 114234, "up": 120, "down": 0 }] },
{ "underlying": "BTC-USD", "expiresAt": 1793308861000, "strikes": [{ "strike": 114235, "up": 0, "down": 40 }] }
]
}
Trading
Trade key.
| Method | Path | Does |
|---|---|---|
POST | /orders | Places an order. 201 {order, positions, canceled} |
POST | /orders/batch | {"cancel"?: [ids], "orders"?: […]}: cancels first (up to 100 ids; any not resting are skipped), then places up to 20 orders in turn, all in one step: nothing else trades in between. {canceled, results}: each result is what POST /orders would return, plus its status, such as {"status": 201, "order", "positions", "canceled"} or {"status": 409, "error": "post-only order would trade"} |
DELETE | /orders/:id | Cancels one. The order |
DELETE | /orders?all=true&market=&side= | Cancels every resting order, or one market's and/or side's, including any you placed in the app. {canceled}. Without all=true it's refused, so leaving out an id never cancels everything |
POST | /me/refill | Back to $1,000 once your balance is below $10. Your account |
Place an order
| Field | ||
|---|---|---|
market | required | Any open market's id from GET /markets, like BTC-15s, GOLD-1m, HOUSE-R-2026, IRAN-STRIKE or CLAUDE-UP-7d |
side | required | up or down |
size | required | 1 to 100,000, at most 2 decimals. Taken from your balance when you place it |
strike | optional | Makes it a limit order at this strike, on the market's grid (strikeOffset + n × strikeStep, inside strikeMin..strikeMax: whole dollars on BTC, $0.10 on gold, half seats on HOUSE-R-2026, a Julian Day Number + 0.5 on a date market, x.5 on ELON). Leave it out for a market order |
tif | optional | Limit orders only. gtc (the default) rests until it fills or you cancel it; ioc takes what it can at the strike or better, then cancels the rest; post only ever rests: if it would trade on arrival (against anyone, your own orders included), it's refused before it touches the book, so it cancels nothing. It isn't kept on the order |
clientId | optional | Your own id for the order, unique per account while the order is kept (a canceled order that never filled, for a day; any other, for good): 1-64 of A-Z a-z 0-9 _ - . : |
# market: fills now at the best strikes available, or fails with 409 no liquidity
-d '{"market": "BTC-15s", "side": "up", "size": 25}'
# limit: rests in the book at 114230 until it fills or you cancel it
-d '{"market": "BTC-1m", "side": "up", "size": 100, "strike": 114230}'
# a maker quote that never takes
-d '{"market": "BTC-15s", "side": "down", "size": 200, "strike": 114236, "tif": "post", "clientId": "ask-1"}'
{
"order": {
"id": "Qm7rL2xV9cNa",
"clientId": null,
"market": "BTC-15s",
"side": "up",
"strike": null,
"size": 25,
"filled": 25,
"status": "filled",
"createdAt": 1793308800105
},
"positions": [
{
"id": "Xq3vT9aLm2Pk",
"orderId": "Qm7rL2xV9cNa",
"market": "BTC-15s",
"side": "up",
"strike": 114234,
"size": 25,
"spot": 114233.2,
"openedAt": 1793308800105,
"expiresAt": 1793308816000,
"settlePrice": null,
"result": null,
"pnl": null
}
],
"canceled": []
}
positions are what the order opened right away; canceled lists your own resting orders it met and canceled on the way. An order's strike is null for a market order, and while it's open, size − filled rests in the book. A market order that couldn't fill all of its size ends canceled with the rest refunded. One that filled nothing is refused with 409 no liquidity and isn't recorded, and an ioc order that filled nothing is refused with 409 no liquidity at that strike. A refusal also lists in canceled any of your resting orders it canceled. A resting order fills later at its own strike, and you hear about it on the WebSocket or by listing positions. If a request fails in transit, send it again with the same clientId: a 409 duplicate clientId carries the orderId it already belongs to.
To re-quote, send one batch: the ids of your current quotes in cancel and the new ones in orders.
Chat
Trade key.
| Method | Path | Does |
|---|---|---|
POST | /chat | {"text", "share"?, "feedback"?, "room"?}: up to 240 characters to the global chat, or with room (an underlying, like HOUSE-R-2026, or an uptime page's room, like CLAUDE-UPTIME) to that market's room. share is one of your settled positions' ids; feedback: true sends it as product feedback (up to 1,000 characters); both go to the global chat. 201 with the message |
PUT | /chat/:id/reactions/:emoji | Puts your reaction on one of the last 50 messages: 👍 🔥 😂 🚀 💀 👀 (URL-encoded in the path). The message as it now stands |
DELETE | /chat/:id/reactions/:emoji | Takes it off. Both are safe to repeat |
Messages sent through the API carry api: true, so people can tell a script from someone typing. Each market has a room beside the global chat: its messages carry room, the underlying's id (an uptime's three lines share their page's room: CLAUDE-UPTIME, POLYMARKET-UPTIME). Both rate limits are shared.
WebSocket
wss://rizon.markets/api/v1/ws. Without a key you get the public channels; with one (an Authorization header, or ?key=rz_… from a browser) you also get your own orders, positions and account, and can trade over the socket.
Pick channels with ?channels=, comma-separated: books is every book and all everything. Leave it out for all of them. A socket that listens to every book also hears each new one when its market opens. With a key, your own order, position and account events come whatever the channels.
| Channel | Events |
|---|---|
price:<underlying>, like price:BTC-USD | price: BTC's on every change, up to 20 a second; gold's on every change and at least every second; an uptime's on every reading, each minute; a book-priced line's midpoint when it changes, at most once a second; ELON's count on every read of the counter, about every 10 s |
book:<market>, like book:BTC-15s | book: one market's book (up to 30 levels a side, with its mid) on every change, up to 10 a second each |
markets | markets: every market (as GET /markets lists them), whenever one opens, closes, halts or resolves |
trades | trade when a trade opens, and again when it settles |
leaderboard | leaderboard, whenever it changes |
chat | chat for each new message in the global chat, and again when its reactions change |
chat:<underlying>, like chat:BTC-USD | the same for one market's room (chat:CLAUDE-UPTIME for claude.ai's three uptime lines; chat:CLAUDE-UPTIME-7D is the same room) |
Every message from the server is {"type", "data"}. Events are named for what they carry; trade and chat are upserts, so keep the latest by id. On connect you get hello, then the current state of each subscribed price, book, leaderboard and the markets, so nothing waits for the next change.
| Event | data |
|---|---|
hello | {t, account, orders, positions, markets, channels}: account is null without a key; orders and positions are your open ones, in the order REST lists them |
price | {underlying, t, price, live} |
book | A book |
markets | Every market |
trade | A trade |
leaderboard | A list of traders |
chat | A chat message |
order · position · account | One of yours, whenever it changes (needs a key) |
You send requests, named for what they do. Each may carry a reqId (a number, or a string of up to 128 characters), and gets one reply: {"type": "ack" | "error", "reqId", "status", "data"}, with the status and body its REST call would return.
| Request | Fields | Same as |
|---|---|---|
subscribe · unsubscribe | channels: [...] | Acked with {channels}: everything you now get |
place | the order's fields (trade key) | POST /orders |
cancel | orderId; or all: true, with market? and side? to narrow it | DELETE /orders/:id, DELETE /orders?all=true |
batch | cancel?, orders? | POST /orders/batch |
ping | Acked with {t}: the server time |
{ "type": "place", "reqId": 1, "market": "BTC-15s", "side": "up", "size": 10 }
{ "type": "order", "data": { "id": "Qm7rL2xV9cNa", "status": "filled", … } }
{ "type": "position", "data": { "id": "Xq3vT9aLm2Pk", "strike": 114234, … } }
{ "type": "account", "data": { "balance": 990, … } }
{ "type": "ack", "reqId": 1, "status": 201, "data": { "order": { … }, "positions": [ … ], "canceled": [] } }
An order's order, position and account events arrive before its reply. For an order placed over REST they're sent before the response, but on another connection, so either can arrive first. Events aren't replayed after a disconnect: hello on reconnect has your open orders and positions, and GET /positions?status=settled has what settled meanwhile.
A Python bot, with the stream and REST together:
import asyncio, json, os, httpx, websockets # websockets 14+
KEY = os.environ["RIZON_API_KEY"]
AUTH = {"Authorization": f"Bearer {KEY}"}
API = "https://rizon.markets/api/v1"
WS = "wss://rizon.markets/api/v1/ws?channels=price:BTC-USD,book:BTC-15s"
async def main():
async with httpx.AsyncClient(base_url=API, headers=AUTH) as rest:
delay = 1
while True:
try:
async with websockets.connect(WS, additional_headers=AUTH) as ws:
delay = 1
async for raw in ws:
m = json.loads(raw)
kind, data = m["type"], m.get("data")
if kind == "hello": # your open orders and positions: rebuild state here
print("open positions:", len(data["positions"]))
elif kind == "price" and not data["live"]:
continue # a simulated price: sit out
elif kind == "position" and data["result"]:
print("settled:", data["result"], data["pnl"])
# decide, then act over REST, or send {"type": "place", ...} on the socket:
# r = await rest.post("/orders", json={"market": "BTC-15s", "side": "up", "size": 10})
except (OSError, websockets.exceptions.WebSocketException) as e: # refused, dropped or closed
print(f"disconnected ({e}), retrying in {delay}s")
await asyncio.sleep(delay)
delay = min(delay * 2, 30)
asyncio.run(main())
In a browser:
const ws = new WebSocket(\`wss://rizon.markets/api/v1/ws?channels=price:BTC-USD,book:BTC-15s&key=${key}\`);
ws.onmessage = (e) => {
const { type, data } = JSON.parse(e.data);
if (type === 'price') console.log(new Date(data.t).toISOString(), data.price, data.live ? '' : '(simulated)');
if (type === 'book') console.log(data.market, data.bids[0]?.strike, data.asks[0]?.strike);
};
MCP
Every call above is also a tool for an AI agent, over the Model Context Protocol, at https://rizon.markets/mcp:
claude mcp add --transport http rizon https://rizon.markets/mcp
The tools are list_markets, get_book, get_prices, get_leaderboard, create_account, get_account, get_positions, get_orders, place_order and cancel_orders. Market data needs no key. For the rest, set your key as the server's bearer token (--header "Authorization: Bearer rz_…") or pass it as each tool's key; create_account makes one.
Errors and limits
Errors are {"error": "…"} with a status, and the message says what to fix.
| Status | Means |
|---|---|
400 | Malformed: a field or parameter is missing, out of range, or not one the endpoint takes |
401 | No key, or a key that isn't valid (revoked?) |
403 | The key's scope doesn't allow it (this key is read-only), or it's for the account's owner |
404 | No such endpoint, market or object (yours only, for orders and positions) |
405 | The path exists but not with this method: see the Allow header |
409 | Valid, but not now. See below |
410 | A connect code that expired |
429 | Too fast: wait Retry-After seconds (also retryAfter in the body, and on WebSocket errors) |
503 | no price yet (just after a restart, or a feed with nothing fresh or only a simulated price: BTC's exchanges both down, gold's venues, an unread status page), or too many connect requests at once |
A trading 409's error is one of these, so a bot can branch on it:
error | Also carries |
|---|---|
insufficient balance | |
no liquidity | canceled, if it canceled any of your orders |
no liquidity at that strike | canceled, likewise |
post-only order would trade | |
duplicate clientId | orderId |
order is already filled · order is already canceled | order |
that market is closed · that market is halted |
A strike off the market's grid, or outside the strikes it takes now (strikeMin to strikeMax), is a 400: strike out of bounds for the second. An order on a market that hasn't opened yet is a 400 too. The other 409s are refill is available once your balance is below 10, name taken, a full key list, and a connect code that was already answered.
A restart (a deploy) drops connections for a few seconds, and a request in that window can fail with a 502 and no JSON. Resting orders and open positions survive it, and positions that expire meanwhile settle once it's back, on the real price at their expiry.
| Limit | |
|---|---|
| REST requests | 20 a second per key (or per address without one), in bursts of up to 40. Each WebSocket connect counts as one; a bad key counts against its address |
| Orders | 20 a second per account, batches and the WebSocket included. Cancels don't count |
| Batch | 20 orders |
| WebSockets | 10 open per key (or per address without one); 20 messages a second from each key or address, in bursts of up to 40 |
| Chat | 1 message per 800 ms and 5 per 10 s; 20 reactions per 10 s |
| New accounts | 20 per hour per address |
| Connect requests | 30 per hour per address |
| Keys | 20 live per account |
Objects
type Side = 'up' | 'down';
interface Market { // an underlying and a horizon, one continuous book
id: string; underlying: string; // 'BTC-15s', 'BTC-USD'; 'HOUSE-R-2026', 'HOUSE-R-2026'
horizon: number | null; // seconds from a fill to its expiry (15); null if not rolling
strikeStep: number; strikeOffset: number; // strikes: strikeOffset + n × strikeStep
spot: number | null; live: boolean; // a feed's value, or the book's latest midpoint; live: false while simulated or stale
bid: number | null; ask: number | null; bidSize: number; askSize: number;
sigma: number; // 1-sigma move over the horizon, in the underlying's units (realised on a feed; a line's on books)
mid: number | null; // the book's midpoint now, (bid + ask) / 2; null while one-sided
kind: 'rolling' | 'fixed' | 'date'; // rolling: each fill expires \`horizon\` seconds after itself
slot: number | null; // rolling: the expiry grid in seconds (1; 86,400 on an uptime: a UTC midnight)
expiresAt: number | null; // fixed: when every position expires (it settles on the resolution)
deadline: number | null; // date: 00:00 UTC on the last day the event can happen on
closesAt: number | null; // fixed and date: when trading stops
status: 'open' | 'closed' | 'halted' | 'resolved';
value: number | null; // what it resolved to; null until then, and when voided
unit: 'usd' | 'count' | 'seats' | 'pct' | 'margin' | 'date' | 'usdbn' | 'uptime'; // how the value is written
name: string; category: string; question: string; rules: string[];
strikeMin: number | null; strikeMax: number | null; // the strikes it takes now, when bounded (a date market's move each midnight)
}
interface Book { market: string; t: number; bids: Level[]; asks: Level[]; mid: number | null } // best first; mid: (best bid + best ask) / 2
interface Level { strike: number; size: number }
interface Order {
id: string; clientId: string | null; market: string; side: Side;
strike: number | null; // null: a market order
size: number; filled: number; // while open, size - filled rests
status: 'open' | 'filled' | 'canceled'; createdAt: number;
}
interface Placed { order: Order; positions: Position[]; canceled: Order[] } // POST /orders
interface Position { // your side of one trade, with the trade's id
id: string; orderId: string | null; market: string; side: Side; strike: number; size: number;
spot: number; // the underlying at the fill
openedAt: number; expiresAt: number; // expiresAt: a whole second (an uptime's, a midnight). Read it, don't compute it
settlePrice: number | null;
result: 'win' | 'loss' | 'push' | null; // null while open
pnl: number | null; // +size, -size or 0
}
interface Exposure { underlying: string; expiresAt: number; strikes: { strike: number; up: number; down: number }[] }
interface Trade { // a fill on the public tape
id: string; market: string; strike: number; size: number; spot: number;
openedAt: number; expiresAt: number;
up: Party | null; down: Party | null; // who's on each side (null only on trades before 2026-10-28)
taker: Side | null; // the side whose order arrived (null only on old trades)
settlePrice: number | null; outcome: Side | 'push' | null; // null while open
}
interface Party { id: string; name: string }
interface Trader {
id: string; name: string; avatar: string | null; rank: number | null;
pnl: number; wins: number; losses: number; pushes: number; streak: number; bestStreak: number;
}
interface Account extends Trader { balance: number; inOrders: number; inPositions: number; equity: number }
interface ChatMessage {
id: string; from: Party; text: string; createdAt: number;
share?: Position; feedback?: true; api?: true;
room?: string; // a market's room (its underlying: 'BTC-USD'; an uptime page's: 'CLAUDE-UPTIME'); absent in the global chat
reactions?: { emoji: string; by: Party[] }[];
}
interface KeyInfo { id: string; name: string; scope: 'trade' | 'read'; hint: string; createdAt: number; lastUsedAt: number | null }
Avatar URLs are paths on https://rizon.markets.