Trade Flex through the API
Use your account’s API key to read the venue, request a firm quote and explicitly accept it.
API-key rollout in progress. Signed Flex access and early exits are undergoing deployment verification. This guide describes the implemented contract; it does not confirm that your key can use every route yet. Competing external maker RFQs are not live.
Create a key and read state
Open Settings → API keys and create a Bot key. Select read for state and portfolio; add trade for quote and acceptance calls. These scopes do not grant withdrawal authority. Account eligibility and available collateral still apply.
Keep the key and its secret in your process environment or secret manager. Do not embed them in browser code, URLs or logs. A website Bearer session is a different credential.
# Python 3.10+, standard library only. This script only reads state. # Supply OMNI_ACCESS_KEY and OMNI_API_SECRET in your environment. # OMNI_API_SECRET is the 64-character hex secret from Settings → API keys. import base64, hashlib, hmac, json, os, time import urllib.request from decimal import Decimal class NoRedirect(urllib.request.HTTPRedirectHandler): def redirect_request(self, *args, **kwargs): return None method, target, body = "GET", "/flex/state", b"" timestamp = str(time.time_ns() // 1_000_000) secret = bytes.fromhex(os.environ["OMNI_API_SECRET"]) # 32 bytes canonical = f"{timestamp}\n{method}\n{target}\n".encode() + body signature = base64.b64encode( hmac.new(secret, canonical, hashlib.sha256).digest()).decode() request = urllib.request.Request("https://api.omnibook.xyz" + target, method=method, headers={ "DX-ACCESS-KEY": os.environ["OMNI_ACCESS_KEY"], "DX-ACCESS-TIMESTAMP": timestamp, "DX-ACCESS-SIGNATURE": signature, "Accept": "application/json", }) with urllib.request.build_opener(NoRedirect()).open(request, timeout=5) as r: state = json.loads(r.read(), parse_float=Decimal) print("Ready:", state.get("ready")) print("Visible positions:", len(state.get("positions", [])))Download the Python client for all six routes, Decimal parsing and explicit unknown-outcome errors. Standard library only; place the file beside your script. It never retries automatically or creates request IDs.
This example makes one read-only request. The direct API origin is
https://api.omnibook.xyz. Browser adapters under/api/flex/*are not the signed developer endpoint.Sign the exact request bytes
Send
DX-ACCESS-KEY,DX-ACCESS-TIMESTAMPandDX-ACCESS-SIGNATURE. The timestamp is decimal Unix milliseconds, within ±5 seconds of the server. The secret is 64 hex characters. Hex-decode it to 32 bytes, compute HMAC-SHA256 with those bytes, then base64-encode the signature.timestamp + "\n" + METHOD + "\n" + path_with_query + "\n" + exact_body_bytesUse an empty body for GET. For POST, serialize JSON once, sign those bytes and send those same bytes. Preserve query encoding and order. Do not combine Bearer and signed-key headers or follow redirects with credentials. A retry needs a fresh timestamp and signature, while retaining the original intent and quote IDs.
Per-owner limits in each accounts process: reads 10/s with burst 20; writes 2/s with burst 4. Respect
retry_after_mson HTTP 429. Creating another key does not reset your owner’s bucket.Quote, inspect and explicitly accept
All paths use https://api.omnibook.xyz Method / path Scope Action GET /flex/stateReadiness, BTC observations, balances and positions. Read Readiness, BTC observations, balances and positions. GET /flex/portfolioListed + Flex valuation; check ready and freshness. Read Listed + Flex valuation; check ready and freshness. POST /flex/quoteRequest an immutable entry quote. No fill yet. Trade Request an immutable entry quote. No fill yet. POST /flex/acceptAccept a saved entry quote ID. Trade Accept a saved entry quote ID. POST /flex/exit/quoteQuote a whole owned position for early exit. Trade Quote a whole owned position for early exit. POST /flex/exit/acceptAccept a saved exit quote ID. Trade Accept a saved exit quote ID. Save a unique
request_idand the intended terms before requesting an entry quote. Choose exactly one of budget (integer cents, 100–10000) or contracts (integer count, 1–100). Duration is 60–3600 seconds.POST /flex/quote {"request_id":"my-entry-001","side":"above","tenor":300,"budget":1000} # Or use "contracts":10 instead of "budget":1000. # Response: id, side, tenor, strike, quantity, price, cost, expires. # Inspect cost and quantity; persist id before accepting. POST /flex/accept {"quote_id":"1234567890123456789"}IDs above are examples, not executable quotes. Keep IDs as decimal strings. The quote’s strike is indicative: the exchange locks the actual strike and start time at execution. Use the returned position’s terms.
POST /flex/exit/quote {"request_id":"my-exit-001","position_id":"1234567890123456789"} # Response: id, position_id, quantity, price, proceeds, expires. # Inspect proceeds; persist this new exit quote id before accepting. POST /flex/exit/accept {"quote_id":"2345678901234567890"}Early exit closes the whole owned position. An exit receipt has
state: "exited",exit_id,exit_tsandexit_proceeds. Its oracle fixing fields and payout are null; exit proceeds are not an expiry settlement.Preserve identity when execution is uncertain
- Persist request IDs and exact terms. Identical quote retries return the original quote and deadline. Changing terms under the same ID is a conflict.
- Persist the returned quote ID before accepting. Quotes normally last 2.5 seconds; use the returned
expires. Do not begin a new acceptance after its deadline. - A matching HTTP 200 execution receipt confirms the trade. Save it. A failed balance refresh does not undo execution.
- A timeout, malformed receipt or HTTP 503 leaves acceptance unknown. Retry acceptance using only the original quote ID, even after expiry. Do not replace it with a new quote.
- HTTP 409 is a terminal rejection for that acceptance. A subsequent intentional trade needs a new request ID. HTTP 401/403/404 or 429 does not resolve a previously unknown execution: repair credentials or back off, then reconcile the original ID.
A 503 during quote creation can also indicate an idempotency conflict or admission limit. Keep that request identity and inspect the response context. Never interpret unavailable as a zero price, zero balance or confirmed rejection.
Keep money, timestamps and settlement distinct
- Quote price/cost, position cost/payout and exit price/proceeds are cents, possibly fractional. Parse fractions as Decimal; divide by 100 for USD.
- Portfolio
available,reserved,positionsandequityare decimal strings in pips: 10,000 pips = $1. Checkready; null is unavailable, not zero. - BTC strike and fixing prices are USD × 100,000,000. Quote expiry, chart ticks and position timestamps are Unix milliseconds. The nested state
oracle.tsuses nanoseconds. - Each correct contract pays $1 gross. Above means strictly above the strike; Below includes equality. Gross payout includes the premium returned and is not net profit.
- Expiry settlement uses a qualifying exchange oracle publication within five seconds after expiry. Without automatic refund policy v1, no timely fixing leaves the position unresolved. When that policy is enabled, a still-open contract is voided at or after 30 seconds past expiry and both original contributions are returned. A refunded receipt has state “refunded”, void_ts and refund; fixing, payout and exit fields are null. It records zero P&L, not a win or loss. Exit, settlement and refund are mutually exclusive.
State includes all open positions plus the newest 200 closed positions, not complete account history. Portfolio valuation includes Listed and Flex claims and must not be reconstructed from this bounded list. Indicative equity is not spendable cash.