Python SDK

The official Python SDK wraps HMAC signing, REST, and WebSocket so agents and bots can trade without assembling headers by hand.

GitHub: OmniBook-HQ/python-sdk-v1
PyPI: omnibook

The SDK can lag the OpenAPI. New endpoints and fields land in the venue spec first. For production bots that must track every surface on day one, generate a client from venue-openapi.yaml (and venue-asyncapi.yaml for WS) rather than waiting on a package release. The SDK remains the fastest path for common flows.

Install

pip install omnibook

Requires Python 3.10+.

Prerequisites

Sign in at omnibook.xyz.
Deposit USDC (bot keys cannot withdraw).
Create a key under Settings → API keys. Copy the API key and secret (shown once).

The SDK talks to the venue (https://api.omnibook.xyz), not the browser session proxy. Pass the 64-character hex secret from Settings, the client hex-decodes it to the raw 32-byte HMAC key for you (legacy base64 secrets still work).

Quick start

from omnibook import Client

with Client(api_key="<alphanumeric-api-key>", api_secret="<64-char-hex-secret>") as client:
    print(client.get_exchange_status())
    rounds = client.get_rounds(limit=5)
    print(rounds)

    markets = client.get_markets(status="trading")
    live = next((m for m in markets["markets"] if m["status"] == "trading"), None)
    if live:
        print(live["market_id"], live.get("tick_size"))

Prices are pip ticks (3500 = 35.00¢). Do not send 1–99. Helpers live in omnibook.ticks — see Ticks, pips, and subcents.

Multi-asset support is partial in the SDK. get_rounds(category=...) scopes to one series, but get_oracle_price() takes no feed argument and therefore always answers feed 0 (BTC). For gold or crude, call the route directly until a release adds the parameter:

client.get("/v1/oracle/price", params={"feed": 1})   # gold

first_trading_market() likewise returns whichever live slot comes first — with nine series that is not necessarily the asset you want. Read the round’s category to confirm. See Series, assets, and categories.

Place an order

from omnibook.ticks import cents_to_tick, on_grid

tick = cents_to_tick(35.00)  # 3500
assert on_grid(tick, live["tick_size"])
order = client.place_order(
    client_order_id="42",          # your idempotency key
    market_id=live["market_id"],
    side="buy",
    outcome="yes",
    type="limit",
    tick=tick,
    qty=10,
    tif="gtc",
    post_only=True,
)
print(order["order_id"], order["status"])
client.cancel_order(order["order_id"])

On a 504 sequencing timeout, retry with the same client_order_id, see Orders.

Async

from omnibook import AsyncClient

async with AsyncClient(api_key="<alphanumeric-api-key>", api_secret="<64-char-hex-secret>") as client:
    balance = await client.get_balance()

WebSocket

One signed connection multiplexes public and private channels. Pass market_ids for orderbook_snapshot / orderbook_delta and trades. Live channels also include oracle, rounds, and user. (ticker is not implemented.) oracle and rounds are global across all nine series — the SDK hands you every frame. Filter on msg["msg"]["feed"] and msg["msg"]["category"] yourself.

with Client(api_key="<alphanumeric-api-key>", api_secret="<64-char-hex-secret>") as client:
    with client.websocket() as ws:
        ws.subscribe(channels=["rounds", "oracle", "user"])
        ws.subscribe(channels=["orderbook_snapshot", "trades"], market_ids=[66])
        for msg in ws:
            if msg.get("_gap"):
                # Public channel gap, prefer update_subscription get_snapshot.
                ...
            print(msg)

Channel details: WebSocket overview and Channels.

Environments

Env	REST	WebSocket
Production (default)	`https://api.omnibook.xyz`	`wss://api.omnibook.xyz/v1/ws`
Local	`http://127.0.0.1:9104`	`ws://127.0.0.1:9105/v1/ws`

Client(
    api_key="...",
    api_secret="...",
    base_url="http://127.0.0.1:9104",
    ws_url="ws://127.0.0.1:9105/v1/ws",
)

Errors

The SDK raises typed exceptions from the venue envelope:

Exception	When
`OmnibookAuthError`	401 / bad signature / clock skew
`OmnibookRateLimitError`	429, check `retry_after`
`OmnibookTimeoutError`	504, retry same `client_order_id`
`OmnibookAPIError`	other HTTP errors (`code`, `origin`, `num`)

Branch on exc.code, not the message. Full list: Errors.

What the SDK covers

Exchange status / schedule / retention
Account limits (scopes, read/write/cancel buckets, trailing volume, batch cap)
Markets, orderbook, trades
Rounds (with category filter) and oracle price (feed 0 only — see above)
Portfolio balance, positions, fills, orders, queue position
Place / batch / cancel / cancel-batch / cancel-all / decrease
Pip tick helpers (cents_to_tick, on_grid, implied_ask, first_trading_market)
Dead-man switch (arm / disarm)
Deposit address (read)
WebSocket subscribe / unsubscribe / update_subscription / stream

Withdrawals and account signup are intentionally out of scope for bot keys.

Running the tests

From the SDK repository:

pip install -e ".[dev]"
pytest                     # unit tests (mocked), always safe

Live venue tests (auth, market data, place+cancel, WebSocket subscribe):

OMNIBOOK_RUN_INTEGRATION=1 \
  OMNIBOOK_API_KEY=... \
  OMNIBOOK_API_SECRET=... \
  OMNIBOOK_BASE_URL=http://127.0.0.1:9104 \
  OMNIBOOK_WS_URL=ws://127.0.0.1:9105/v1/ws \
  pytest -m integration

Prefer the local venue when available. Place-order tests use tiny post_only sizes (pip ticks, e.g. 100 = 1.00¢) and cancel in teardown.

Prefer raw HTTP?

See Authentication for HMAC header details in Python, TypeScript, and cURL without the SDK.

Get started

SDKs

Strategies

Concepts

Changelog

Install

Prerequisites

Quick start

Place an order

Async

WebSocket

Environments

Errors

What the SDK covers

Running the tests

Prefer raw HTTP?

​Install

​Prerequisites

​Quick start

​Place an order

​Async

​WebSocket

​Environments

​Errors

​What the SDK covers

​Running the tests

​Prefer raw HTTP?

Install

Prerequisites

Quick start

Place an order

Async

WebSocket

Environments

Errors

What the SDK covers

Running the tests

Prefer raw HTTP?