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

Flex API
BTC Flex

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.

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

  2. Sign the exact request bytes

    Send DX-ACCESS-KEY, DX-ACCESS-TIMESTAMP and DX-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_bytes

    Use 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_ms on HTTP 429. Creating another key does not reset your owner’s bucket.

  3. Quote, inspect and explicitly accept

    All paths use https://api.omnibook.xyz
    Method / pathScopeAction
    GET /flex/stateReadiness, BTC observations, balances and positions.ReadReadiness, BTC observations, balances and positions.
    GET /flex/portfolioListed + Flex valuation; check ready and freshness.ReadListed + Flex valuation; check ready and freshness.
    POST /flex/quoteRequest an immutable entry quote. No fill yet.TradeRequest an immutable entry quote. No fill yet.
    POST /flex/acceptAccept a saved entry quote ID.TradeAccept a saved entry quote ID.
    POST /flex/exit/quoteQuote a whole owned position for early exit.TradeQuote a whole owned position for early exit.
    POST /flex/exit/acceptAccept a saved exit quote ID.TradeAccept a saved exit quote ID.

    Save a unique request_id and 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_ts and exit_proceeds. Its oracle fixing fields and payout are null; exit proceeds are not an expiry settlement.

  4. Preserve identity when execution is uncertain

    1. Persist request IDs and exact terms. Identical quote retries return the original quote and deadline. Changing terms under the same ID is a conflict.
    2. 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.
    3. A matching HTTP 200 execution receipt confirms the trade. Save it. A failed balance refresh does not undo execution.
    4. 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.
    5. 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.

  5. 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, positions and equity are decimal strings in pips: 10,000 pips = $1. Check ready; 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.ts uses 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.

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