Authentication

Every request to the Omnibook API is authenticated. There is no anonymous access, even market data requires a key.

Using Python? Prefer the Python SDK, it signs requests and opens the WebSocket for you. The rest of this page is the raw HMAC contract (useful for other languages and for understanding what the SDK does).

You authenticate by signing each request with your API key’s secret and sending three headers. Nothing is sent as a bearer token, so intercepting a request does not give anyone your key.

Create an API key

Sign in at omnibook.xyz.
Go to Settings → API keys (/settings#keys).
Click Create key, give it a name, and copy both values.

The secret is shown once and never again. Store it somewhere safe before you close the panel. Copy the API key too, you need both, and the list view does not show the secret again.If you lose a secret, revoke the key and create a new one. Revoking is immediate and irreversible.

The three headers

Header	Value
`DX-ACCESS-KEY`	Your API key (alphanumeric string)
`DX-ACCESS-TIMESTAMP`	Current Unix time in milliseconds, in decimal
`DX-ACCESS-SIGNATURE`	`base64(HMAC-SHA256(secret, canonical))`

The canonical string

The signature covers the timestamp, method, request target and body, joined by newlines, with a trailing newline after the target:

<timestamp> \n <METHOD> \n <request-target> \n <body>

Concretely, for GET /v1/portfolio/balance with no body:

1785299414489\nGET\n/v1/portfolio/balance\n

Three things that catch people out:

The request target includes the query string. Sign /v1/rounds?limit=5, not /v1/rounds.
The body is the raw bytes you send, byte-for-byte. If you re-serialize your JSON between signing and sending, the signature breaks.
The signature covers the body, so you cannot sign once and replay with different parameters.

Hex-decode your secret before using it as the HMAC key.The secret is 32 random bytes, handed to you as 64 hex characters ([0-9a-f]). The HMAC key is those 32 raw bytes, not the 64-character string.Using the string directly produces a perfectly valid-looking signature and a permanent 401. This is the single most common integration bug.

Working examples

import hashlib, hmac, json, time
import requests

BASE = "https://api.omnibook.xyz"
API_KEY = "<your alphanumeric API key>"
SECRET = bytes.fromhex("<your 64-char hex secret>")   # 32 raw bytes

def request(method, target, body=b""):
    ts = str(int(time.time() * 1000))
    canonical = f"{ts}\n{method}\n{target}\n".encode() + body
    sig = __import__("base64").b64encode(
        hmac.new(SECRET, canonical, hashlib.sha256).digest()
    ).decode()
    return requests.request(
        method, BASE + target, data=body,
        headers={
            "DX-ACCESS-KEY": API_KEY,
            "DX-ACCESS-TIMESTAMP": ts,
            "DX-ACCESS-SIGNATURE": sig,
            "Content-Type": "application/json",
        },
    )

print(request("GET", "/v1/portfolio/balance").json())

import { createHmac } from "node:crypto";

const BASE = "https://api.omnibook.xyz";
const API_KEY = "<your alphanumeric API key>";
const SECRET = Buffer.from("<your 64-char hex secret>", "hex"); // 32 raw bytes

export async function request(method: string, target: string, body = "") {
  const ts = Date.now().toString();
  const canonical = `${ts}\n${method}\n${target}\n${body}`;
  const sig = createHmac("sha256", SECRET).update(canonical).digest("base64");

  return fetch(BASE + target, {
    method,
    body: body || undefined,
    headers: {
      "DX-ACCESS-KEY": API_KEY,
      "DX-ACCESS-TIMESTAMP": ts,
      "DX-ACCESS-SIGNATURE": sig,
      "Content-Type": "application/json",
    },
  });
}

console.log(await (await request("GET", "/v1/portfolio/balance")).json());

TS=$(date +%s000)
TARGET="/v1/portfolio/balance"
API_KEY="<your alphanumeric API key>"
SECRET_HEX="<your 64-char hex secret>"

SIG=$(printf '%s\nGET\n%s\n' "$TS" "$TARGET" \
  | openssl dgst -sha256 -mac HMAC \
      -macopt "hexkey:${SECRET_HEX}" \
      -binary | base64)

curl -s "https://api.omnibook.xyz$TARGET" \
  -H "DX-ACCESS-KEY: $API_KEY" \
  -H "DX-ACCESS-TIMESTAMP: $TS" \
  -H "DX-ACCESS-SIGNATURE: $SIG"

Clock skew

Your timestamp must be within ±5 seconds of the server’s clock. Outside that window the request is rejected as a replay, with the same 401 as a bad signature. If you see intermittent 401s that go away on retry, check your clock before you check your signing code.

Why a request failed

Every authentication failure returns the same response:

{ "error": { "code": "unauthorized", "origin": "gateway", "message": "unauthorized" } }

This is deliberate, an unknown API key, a bad signature, and a stale timestamp are indistinguishable, so probing tells an attacker nothing. Work through the list in order:

Did you hex-decode the secret?
Does the signed target include the query string?
Is the signed body byte-identical to what you sent?
Is your clock within 5 seconds?
Is the key still live? A revoked key cannot be restored.

Complete script

Self-contained, paste your key and secret, then run:

#!/usr/bin/env python3
"""Sign a request and read portfolio balance."""
import base64, hashlib, hmac, json, time
import requests

BASE = "https://api.omnibook.xyz"
API_KEY = "<your alphanumeric API key>"
SECRET = bytes.fromhex("<your 64-char hex secret>")  # 32 raw bytes


def request(method, target, body=b""):
    ts = str(int(time.time() * 1000))
    canonical = f"{ts}\n{method}\n{target}\n".encode() + body
    sig = base64.b64encode(
        hmac.new(SECRET, canonical, hashlib.sha256).digest()
    ).decode()
    return requests.request(
        method, BASE + target, data=body,
        headers={
            "DX-ACCESS-KEY": API_KEY,
            "DX-ACCESS-TIMESTAMP": ts,
            "DX-ACCESS-SIGNATURE": sig,
            "Content-Type": "application/json",
        },
    )


resp = request("GET", "/v1/portfolio/balance")
print(json.dumps(resp.json(), indent=2))

Scopes

Keys carry scopes, and a bot key cannot withdraw funds. See API keys and scopes.

Get started

SDKs

Strategies

Concepts

Changelog

Create an API key

The three headers

The canonical string

Working examples

Clock skew

Why a request failed

Complete script

Scopes

​Create an API key

​The three headers

​The canonical string

​Working examples

​Clock skew

​Why a request failed

​Complete script

​Scopes

Create an API key

The three headers

The canonical string

Working examples

Clock skew

Why a request failed

Complete script

Scopes