The new terminal is now live. Feel free to test it and report any bugs on Discord.

Testnet · OmniUSD play money, not real money. Trading can lose the full cost of a position.Testnet · play money, not real money

API

BTC digital options API

Testnet. Read every open strike, stream its book and trade from your own code. Play money.

  1. Strikes open now

    Reading the bootstrap…

    ContractMarket idIdGenerationUp bidUp ask
    Loading…

    Read every 3 s from GET /public/market-bootstrap?category=1, field strikes[]. Prices shown in cents; the API sends pips.

    Reading the bootstrap…

    ContractMarket idIdGenerationUp bidUp ask
    Loading…

    Read every 3 s from GET /public/market-bootstrap?category=2, field strikes[]. Prices shown in cents; the API sends pips.

  2. 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=1

    Each row of strikes[] is a round plus its touch:

    {
      "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=2 for the 5-minute rounds, category=1 for the 1-minute rounds. depth and trade_limit must be 1, 20 or 40.
    • touch is the Up side (Yes). Down's ask is 10,000 − best_yes_bid. Any touch field can be null: no offer.
    • current carries the middle strike's book and trades. For the others, use the socket or GET /proxy/v1/markets/{id}/orderbook.
    • Settled rounds: GET /proxy/v1/rounds?category=2&limit=100 (or category=1). Group rows by close_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.
  3. 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 series subscription 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_id to 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, freeze or settle.
    • A wrong series_id is acknowledged and then sends nothing. The live series are ob-btc-ud-5m (5-minute) and ob-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, user channel. Sign the upgrade like a REST call, with target /v1/ws and an empty body (signed socket).
    OffsetBytesField
    01version: 1
    11type: 1 book snapshot, 2 book delta, 3 trade, 4 oracle, 5 round
    24sid: your subscription
    68seq
    148market_id
    228round_number
    308open_ts, Unix ns
    381status: 1 created, 2 trading, 3 frozen, 4 proposed, 5 settled, 6 void
    391series_id length n
    40nseries_id
    40+n4message length m
    44+nmmessage, JSON
  4. 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 *_ts is Unix nanoseconds, as a decimal string.
    • yes_payout is cents: 0, 50 or 100.
    • Ticks: 1¢ steps from 4¢ to 96¢, 0.1¢ steps outside that (tick_size "narrow": wing_lo 400, wing_hi 9600, tick_step 10).
    • 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).
  5. 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. Use generation; ignore gen.
    • 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 by close_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.
  6. 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) and DX-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_bytes
    import 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". tick is that side's price in pips.
    • Send the strike's generation as 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_id is a decimal string, unique per key. Use a random 63-bit number or time.time_ns(). Small or sequential ids can be refused as duplicates.
    • Your orders: GET /v1/portfolio/orders?status=resting,partially_filled. Omit market_id to list all your orders; add market_id=199 to filter.
    • GET /v1/portfolio/fills keeps 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.
  7. 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": true to cancel your resting order instead (stp_maker) and keep matching.
    • Size. qty is 1 to 100,000,000 contracts per order. More is 403 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_tick defaults to 9990 for a buy and 10 for a sell. A market buy needs max_cost.
    • Batches. POST /v1/portfolio/orders/batch with {"orders":[…]}, or DELETE it with {"order_ids":[…]}. Up to 20 items; more is 400 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_limited with details.retry_after_ms. Your numbers: GET /v1/account/limits.
    • Dead-man switch. POST /v1/portfolio/deadman with {"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. DELETE it to switch off. It is per account, not per key.
    • Duplicates. A client_order_id this key sent in its last 1,024 orders gets 409 duplicate_client_order_id. Never a second order.
    • Timeouts. 504 sequencing_timeout means no answer in 2 s. The order may still land. Read GET /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.
  8. Docs

Testnet runs on OmniUSD credits, not real money. Ids, fields and limits can change between releases: see the changelog.

Trading on Omnibook involves risk and may not be appropriate for everyone. You can lose the full cost of any position, including fees. Season 1 runs on testnet: OmniUSD (testnet credits), not real money.

Command menu

Go to a market, trade or change the view