BTC digital options API
Testnet. Read every open strike, stream its book and trade from your own code. Play money.
Strikes open now
Reading the bootstrap…
Contract Market idId Generation Up bid Up ask Loading… Read every 3 s from
GET /public/market-bootstrap?category=1, fieldstrikes[]. Prices shown in cents; the API sends pips.Reading the bootstrap…
Contract Market idId Generation Up bid Up ask Loading… Read every 3 s from
GET /public/market-bootstrap?category=2, fieldstrikes[]. Prices shown in cents; the API sends pips.Read the open strikes
One public call, no key. It lists every strike of the round trading now.
GET https://api.omnibook.xyz/public/market-bootstrap?category=2&depth=1&trade_limit=1Each row of
strikes[]is a round plus itstouch:{ "market_id": 199, "generation": 55, "status": "trading", "strike": "7375000000000", "close_ts": "1794360900000000000", "round_number": "336883", "touch": { "best_yes_bid": 4900, "best_yes_ask": 6000, "tick_size": { "policy": "narrow", "tick_step": 10, "wing_lo": 400, "wing_hi": 9600 } } }- Always pass the category:
category=2for the 5-minute rounds,category=1for the 1-minute rounds.depthandtrade_limitmust be 1, 20 or 40. touchis the Up side (Yes). Down's ask is 10,000 −best_yes_bid. Any touch field can be null: no offer.currentcarries the middle strike's book and trades. For the others, use the socket orGET /proxy/v1/markets/{id}/orderbook.- Settled rounds:
GET /proxy/v1/rounds?category=2&limit=100(orcategory=1). Group rows byclose_ts. The middle strike's row sorts about 16 rows below the others, so read 100 and drop the groups in the last 20 rows. There is no status filter: filter on your side. - Take the settle price and winner from these rows. They land about 1 s after the close.
- Always pass the category:
Stream books and trades
The public socket needs no key:
wss://api.omnibook.xyz/stream {"id":1,"cmd":"subscribe","params":{"channels":["series"],"series_id":"ob-btc-ud-5m"}}- One
seriessubscription carries every strike: book snapshots (about 5 a second each), deltas, trades, oracle and round frames. - Replies are JSON. Data frames are binary, little-endian, laid out below.
- Frames carry no strike. Map
market_idto its strike with the bootstrap. - The series also streams the next round's slots before they open, with empty books. Skip book frames (types 1 and 2) whose status is not 2 (trading).
- Never filter round frames (type 5) on status. The freeze and settle frames are not stamped trading. Act on
msg.action:create,open,freezeorsettle. - A wrong
series_idis acknowledged and then sends nothing. The live series areob-btc-ud-5m(5-minute) andob-btc-ud-60s(1-minute): one subscription each, on the same socket. - The freeze frame's price is the last oracle tick, not the final price. Read the settle price from REST.
- Your own orders and fills stream on the signed socket
wss://api.omnibook.xyz/v1/ws,userchannel. Sign the upgrade like a REST call, with target/v1/wsand an empty body (signed socket).
Offset Bytes Field 0 1 version: 1 1 1 type: 1 book snapshot, 2 book delta, 3 trade, 4 oracle, 5 round 2 4 sid: your subscription 6 8 seq 14 8 market_id 22 8 round_number 30 8 open_ts, Unix ns 38 1 status: 1 created, 2 trading, 3 frozen, 4 proposed, 5 settled, 6 void 39 1 series_id length n 40 n series_id 40+n 4 message length m 44+n m message, JSON - One
Units
- Book prices, touch and order ticks are pips: 100 pips = 1¢, 10,000 pips = $1.
- Strikes, oracle and settle prices are dollars × 100,000,000, as decimal strings.
"7375000000000"is $73,750. - Every
*_tsis Unix nanoseconds, as a decimal string. yes_payoutis cents: 0, 50 or 100.- Ticks: 1¢ steps from 4¢ to 96¢, 0.1¢ steps outside that (
tick_size"narrow":wing_lo400,wing_hi9600,tick_step10). - BTC > $73,750 @ 5m: Up pays $1 if the final price is strictly above $73,750. Down pays $1 at or below. A void pays 50¢ to each side. All strikes of a round share one final price: the 10-second average of the oracle up to the close (Oracle).
Market ids and rounds
- Two series run side by side. 5-minute rounds end on the 5-minute marks, 1-minute rounds on every minute, UTC.
- 5m: up to 5 strikes on a $50 grid. The middle one is the opening price rounded to the nearest $50 (a tie rounds down), then ±$50 and ±$100. 1m: the same on a $20 grid (±$20, ±$40). Some rounds list fewer.
- Every strike is its own
market_id. 5m: the middle strike uses 192–199, the others 200–263. 1m: the middle strike uses 332–343, the others 128–191. - Ids are reused, so a strike is
market_id+generation. Usegeneration; ignoregen. - A round is the strikes of one series that share one
close_ts. At :00 and :05 a 1-minute and a 5-minute round close together: group by series (its category) first, then byclose_ts. - A strike of
"0"is a voided strike. Orders are refused and it pays 50¢ to each side. - History from before 9 Nov also has 5-minute rounds on ids 74–81, and 1-minute rounds on ids 64–73.
Place orders
Orders go to the signed API at
https://api.omnibook.xyz/v1. Create a Bot key in Settings → API keys. Wallet-only (MetaMask) accounts can't make keys: link Google, X or Discord first.Sign every request with
DX-ACCESS-KEY,DX-ACCESS-TIMESTAMP(Unix ms, within 5 s) andDX-ACCESS-SIGNATURE. The secret is 64 hex characters. Hex-decode it to 32 bytes, HMAC-SHA256 this string, and send the result as base64:timestamp + "\n" + METHOD + "\n" + path_with_query + "\n" + exact_body_bytesimport base64, hashlib, hmac, os, time KEY = os.environ["OMNI_ACCESS_KEY"] SECRET = bytes.fromhex(os.environ["OMNI_API_SECRET"]) # 64 hex chars -> 32 bytes def signed_headers(method, target, body=b""): ts = str(time.time_ns() // 1_000_000) msg = f"{ts}\n{method}\n{target}\n".encode() + body sig = base64.b64encode(hmac.new(SECRET, msg, hashlib.sha256).digest()).decode() return {"DX-ACCESS-KEY": KEY, "DX-ACCESS-TIMESTAMP": ts, "DX-ACCESS-SIGNATURE": sig}Send the exact body bytes you signed:
POST /v1/portfolio/orders { "client_order_id": "1794400000000000001", "market_id": 199, "generation": 55, "side": "buy", "outcome": "yes", "type": "limit", "tick": 4900, "qty": 10, "tif": "gtc" }- Up is
"outcome": "yes", Down is"no".tickis that side's price in pips. - Send the strike's
generationas a JSON number. If the id has moved on to a new strike, the order is refused (409 market_stale) instead of landing on the wrong one. A missing or non-number generation turns this check off. client_order_idis a decimal string, unique per key. Use a random 63-bit number ortime.time_ns(). Small or sequential ids can be refused as duplicates.- Your orders:
GET /v1/portfolio/orders?status=resting,partially_filled. Omitmarket_idto list all your orders; addmarket_id=199to filter. GET /v1/portfolio/fillskeeps only your newest 256 fills. Older ones drop silently. For totals, see fills and cost basis.- Errors are
{"error":{"code":"market_stale",…}}. Codes are lower case. All codes: testnet errors. - Keep the key and secret in your process, never in browser code. Public reads send no CORS headers, so call them from a script or server too.
- Up is
Order rules
- Self-trade. If your order would trade with your own resting order, the rest of the incoming order is cancelled (reason
stp_taker). Fills before that stand. Send"stp_maker": trueto cancel your resting order instead (stp_maker) and keep matching. - Size.
qtyis 1 to 100,000,000 contracts per order. More is403 size_cap_exceeded. - Ticks. 1¢ steps from 4¢ to 96¢, 0.1¢ steps below 4¢ and above 96¢. The grid is the same for every strike and never changes. Off-grid is
400 bad_price_tick. - Market orders.
worst_tickdefaults to 9990 for a buy and 10 for a sell. A market buy needsmax_cost. - Batches.
POST /v1/portfolio/orders/batchwith{"orders":[…]}, orDELETEit with{"order_ids":[…]}. Up to 20 items; more is400 batch_too_large. Each item succeeds or fails on its own. - Rate. One token per HTTP request, a batch included. Reads: 100/s, burst 200. Writes: 20/s plus 1/s per 100,000 contracts you traded in the last 30 days, up to 400/s, re-set every hour (a new key has 50/s until then). Cancels have their own bucket at twice your write rate. Over it:
429 rate_limitedwithdetails.retry_after_ms. Your numbers:GET /v1/account/limits. - Dead-man switch.
POST /v1/portfolio/deadmanwith{"timeout_ms":5000}(1,000 to 60,000). Call it again before it runs out. If it runs out, every open order on your account is cancelled.DELETEit to switch off. It is per account, not per key. - Duplicates. A
client_order_idthis key sent in its last 1,024 orders gets409 duplicate_client_order_id. Never a second order. - Timeouts.
504 sequencing_timeoutmeans no answer in 2 s. The order may still land. ReadGET /v1/portfolio/orders?client_order_id=…before you send anything new. Re-sending the same id is safe: it gets a 409, never a second order.
- Self-trade. If your order would trade with your own resting order, the rest of the incoming order is cancelled (reason
Docs
- Testnet API referencedocs.omnibook.xyz/testnet
- Rounds and strikesdocs.omnibook.xyz/testnet-rounds
- Oracle and final priceSources, the 10 s final price, voids
- RulesWhat every contract pays
- Signed socketYour orders and fills, live
- Error codesEvery code, its status, and what to do
- ChangelogWhat changed, by date
- Flex APIYour own strike and expiry
Testnet runs on OmniUSD credits, not real money. Ids, fields and limits can change between releases: see the changelog.