Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Instrument names

The API names an option contract by two integers:
  • underlyingKey: the underlying, a 64-bit key assigned when the underlying is listed. Find them at GET /v1/underlyings.
  • specifier (optionSpecifier in an order): the contract within that underlying, packing its expiry, strike and right.
In a URL or a WebSocket channel both are written in decimal: /v1/book/7/859008923130267914, book:7:859008923130267914.

The specifier

BitsFieldValue
63–32Expirywhole seconds since 2020-01-01T00:00:00Z
31–12Strikemicros: 50000, 100000, …, 950000
11Right0 call, 1 put
10–8Style1, European
7–0Multiplier ÷ 1010
specifier = expirySeconds << 32 | strike << 12 | right << 11 | 1 << 8 | 10
The expiry must be a whole number of seconds; an instrument's expiryMs is that times 1000. A specifier that decodes to anything other than a listed strike, European style and a multiplier of 100 names no contract, and the gateway refuses an order for it.
def encode(strike: int, right: int, expiry_ms: int) -> int:
    assert expiry_ms % 1000 == 0
    return (expiry_ms // 1000) << 32 | strike << 12 | right << 11 | 1 << 8 | 10

def decode(spec: int) -> dict:
    return {
        "expiryMs": (spec >> 32) * 1000,
        "strike": (spec >> 12) & 0xFFFFF,
        "right": (spec >> 11) & 1,
    }

Examples

StrikeRightExpiry (engine ms)Specifier
50000call200003600000859008921287065866 (0x0bebd0100c35010a)
500000put200003600000859008923130267914 (0x0bebd0107a12090a)
Specifiers are above 253, so JavaScript's Number cannot hold them. Use BigInt, and a JSON parser that keeps large integers.

The expiry bucket

Contracts that share an underlying and an expiry settle together, as one bucket. Its id is 32 bytes: underlyingKey << 64 | expiryMs, big-endian. It appears as 64 hex characters in the instrument catalog and in your account's books, and the settlement contract uses it to post settlement prices and pay claims.

The catalog

GET /v1/instruments lists every listed contract with its strike, right, expiry, bucket and fee rates, so most clients never encode a specifier themselves. They pick one from the catalog.