Request Snapshots

Request fresh snapshots for one or more subscriptions.

RECEIVE/ws

Authorization

UDX-Access-KeyAPI key · headerrequired

Opaque API key ID.

UDX-Access-TimestampAPI key · headerrequired

Unix time in milliseconds, within 30 seconds of server time.

UDX-Access-SignatureAPI key · headerrequired

Standard-base64 RSA-PSS/SHA-256 signature with a 32-byte salt. Sign timestamp + "GET" + "/ws"; the upgrade request has no body hash and no idempotency key.

Commands

snapshotRequest fresh snapshots for the given subscriptions.

idCommandIdrequired

Client-assigned command correlation identifier, unique among commands in flight on this connection.

min 1 · max 9007199254740991

cmdstringrequired

Selects the snapshot command.

paramsSnapshotCommandParamsrequired

Selects subscriptions as a canonical array.

Show properties

sidsSubscriptionIdListrequired

Canonical non-empty list of distinct subscription identifiers.

min items 1 · max items 250

Replies

orderbook_snapshotReturn one snapshot correlated to a snapshot command.

idCommandIdrequired

Client-assigned command correlation identifier, unique among commands in flight on this connection.

min 1 · max 9007199254740991

typestringrequired

Identifies a complete order book snapshot.

sidSubscriptionIdrequired

Exchange-assigned subscription ID whose lifetime is this WebSocket connection.

min 1 · max 9007199254740991

seqSequenceNumberrequired

Gap-detection sequence local to one subscription. It starts at 1 and increments once per frame on that subscription.

min 1 · max 9007199254740991

msgOrderbookSnapshotPayloadrequired

Complete visible L1, L2, or L3 order book state for one market.

Show properties

Any of:

AggregatedOrderbookSnapshotPayload

tickerTickerrequired

A human-meaningful natural key naming a single-leg or multi-leg market.

min length 1 · max length 128

bidsPriceLevel[]required

Bid levels in best-first order as [price, quantity] pairs.

asksPriceLevel[]required

Ask levels in best-first order as [price, quantity] pairs.

L3OrderbookSnapshotPayload

tickerTickerrequired

A human-meaningful natural key naming a single-leg or multi-leg market.

min length 1 · max length 128

bidsL3OrderbookEntry[]required

Anonymous bid orders in best-price, FIFO order across the requested price-level depth.

Show properties

Array of L3OrderbookEntry

entry_idstringrequired

Stable market-data entry handle. It is deliberately not the exchange order ID returned to the order owner.

min length 1

priceFixedPointPricerequired

YES-side price in dollars as an exact fixed-point decimal string with at most six decimal places.

max length 24 · matches ^[0-9]+(\.[0-9]{1,6})?$

quantityFixedPointQuantityrequired

A quantity in contracts as a fixed-point decimal string.

max length 24 · matches ^[0-9]+(\.[0-9]{1,2})?$

asksL3OrderbookEntry[]required

Anonymous ask orders in best-price, FIFO order across the requested price-level depth.

Show properties

Array of L3OrderbookEntry

entry_idstringrequired

Stable market-data entry handle. It is deliberately not the exchange order ID returned to the order owner.

min length 1

priceFixedPointPricerequired

YES-side price in dollars as an exact fixed-point decimal string with at most six decimal places.

max length 24 · matches ^[0-9]+(\.[0-9]{1,6})?$

quantityFixedPointQuantityrequired

A quantity in contracts as a fixed-point decimal string.

max length 24 · matches ^[0-9]+(\.[0-9]{1,2})?$

rate_limitobject

Present only on the first snapshot in this command's finite result series; later snapshots from the same command omit it.

Show properties

bucketstringrequired

Shared member bucket consulted for this command.

Allowed:readwritecancel

capacityinteger<int64>required

Maximum tokens held by the bucket.

min 1 · max 10000000

refill_tokens_per_minuteinteger<int64>required

Tokens restored per minute.

min 1 · max 10000000

remaininginteger<int64>required

Tokens remaining after th decision.

min 0 · max 10000000

full_after_msinteger<int64>required

Milliseconds until the bucket is full if no more work is admitted.

min 0 · max 86400000

Errors

invalid_messageThe JSON or common command envelope is invalid.

codestringrequired

Stable machine-readable error code.

detailErrorDetailrequired

Human-readable occurrence detail that clients must not parse.

min length 1 · max length 500

instanceErrorInstancerequired

Request identifier for troubleshooting with exchange support.

max length 100 · matches ^urn:request-id:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

fieldstring

JSON path to the invalid field when one can be identified.

min length 1 · max length 255

invalid_paramsCommand params fail schema or semantic validation.

codestringrequired

Stable machine-readable error code.

detailErrorDetailrequired

Human-readable occurrence detail that clients must not parse.

min length 1 · max length 500

instanceErrorInstancerequired

Request identifier for troubleshooting with exchange support.

max length 100 · matches ^urn:request-id:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

fieldstring

JSON path to the invalid param when one can be identified.

min length 1 · max length 255

command_id_in_useAnother command with the supplied identifier is still in flight.

codestringrequired

Stable machine-readable error code.

detailErrorDetailrequired

Human-readable occurrence detail that clients must not parse.

min length 1 · max length 500

instanceErrorInstancerequired

Request identifier for troubleshooting with exchange support.

max length 100 · matches ^urn:request-id:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

subscription_not_foundThe subscription identifier is not active on this connection.

codestringrequired

Stable machine-readable error code.

detailErrorDetailrequired

Human-readable occurrence detail that clients must not parse.

min length 1 · max length 500

instanceErrorInstancerequired

Request identifier for troubleshooting with exchange support.

max length 100 · matches ^urn:request-id:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

sidSubscriptionIdrequired

Exchange-assigned subscription ID whose lifetime is this WebSocket connection.

min 1 · max 9007199254740991

subscription_not_readyCurrent state is not yet established for the requested operation.

codestringrequired

Stable machine-readable error code.

detailErrorDetailrequired

Human-readable occurrence detail that clients must not parse.

min length 1 · max length 500

instanceErrorInstancerequired

Request identifier for troubleshooting with exchange support.

max length 100 · matches ^urn:request-id:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

snapshot_in_progressThe subscription already has a snapshot command in flight.

codestringrequired

Stable machine-readable error code.

detailErrorDetailrequired

Human-readable occurrence detail that clients must not parse.

min length 1 · max length 500

instanceErrorInstancerequired

Request identifier for troubleshooting with exchange support.

max length 100 · matches ^urn:request-id:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

channel_unavailableThe channel's upstream source cannot serve the operation right now. Retry with backoff; the connection stays usable.

codestringrequired

Stable machine-readable error code.

detailErrorDetailrequired

Human-readable occurrence detail that clients must not parse.

min length 1 · max length 500

instanceErrorInstancerequired

Request identifier for troubleshooting with exchange support.

max length 100 · matches ^urn:request-id:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

capacity_exceededA standing-resource limit prevents command admission.

codestringrequired

Stable machine-readable error code.

detailErrorDetailrequired

Human-readable occurrence detail that clients must not parse.

min length 1 · max length 500

instanceErrorInstancerequired

Request identifier for troubleshooting with exchange support.

max length 100 · matches ^urn:request-id:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

scopestringrequired

Boundary at which the standing-resource limit applies.

Allowed:connectionmemberprocess

resourcestringrequired

Retained or concurrent resource that reached its limit.

Allowed:in_flight_commandsactive_subscriptionsmarket_data_streams

limitinteger<int64>required

Enforced maximum for the identified scope and resource.

min 1 · max 10000000

rate_limit_exceededA command rate limit was exceeded.

codestringrequired

Stable machine-readable error code.

detailErrorDetailrequired

Human-readable occurrence detail that clients must not parse.

min length 1 · max length 500

instanceErrorInstancerequired

Request identifier for troubleshooting with exchange support.

max length 100 · matches ^urn:request-id:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

retry_after_msinteger<int64>required

Minimum delay in milliseconds before another attempt.

min 1 · max 86400000

admission_unavailableShared admission policy or state is temporarily unavailable.

codestringrequired

Stable machine-readable error code.

detailErrorDetailrequired

Human-readable occurrence detail that clients must not parse.

min length 1 · max length 500

instanceErrorInstancerequired

Request identifier for troubleshooting with exchange support.

max length 100 · matches ^urn:request-id:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

internal_errorAn unexpected failure left connection state safe to continue.

codestringrequired

Stable machine-readable error code.

detailErrorDetailrequired

Human-readable occurrence detail that clients must not parse.

min length 1 · max length 500

instanceErrorInstancerequired

Request identifier for troubleshooting with exchange support.

max length 100 · matches ^urn:request-id:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Channel Bindings

ws

methodGET

headers

UDX-Access-Keystringrequired

Opaque API key ID.

min length 1 · max length 255

UDX-Access-Timestampstringrequired

Unix time in milliseconds, within 30 seconds of server time.

max length 13 · matches ^[0-9]{13}$

UDX-Access-Signaturestringrequired

Standard-base64 RSA-PSS/SHA-256 signature with a 32-byte salt. Sign timestamp + "GET" + "/ws"; the upgrade request has no body hash and no idempotency key.

min length 1 · max length 1024

Sec-WebSocket-Protocolstringrequired

Negotiated dated WebSocket API version.

Examples

snapshot

{
  "id": 3,
  "cmd": "snapshot",
  "params": {
    "sids": [
      7,
      8
    ]
  }
}

orderbook_snapshot

{
  "id": 3,
  "type": "orderbook_snapshot",
  "sid": 7,
  "seq": 18,
  "msg": {
    "ticker": "UDX-EXAMPLE-MARKET-A",
    "bids": [
      [
        "0.45",
        "100"
      ]
    ],
    "asks": [
      [
        "0.47",
        "80"
      ]
    ]
  },
  "rate_limit": {
    "bucket": "read",
    "capacity": 30,
    "refill_tokens_per_minute": 900,
    "remaining": 9,
    "full_after_ms": 1400
  }
}

invalid_message

{
  "type": "error",
  "msg": {
    "code": "invalid_message",
    "detail": "WebSocket command is not a valid JSON object",
    "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
  }
}

invalid_params

{
  "id": 4,
  "type": "error",
  "msg": {
    "code": "invalid_params",
    "detail": "the orderbook channel requires tickers",
    "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef",
    "field": "params.channels"
  }
}

command_id_in_use

{
  "id": 4,
  "type": "error",
  "msg": {
    "code": "command_id_in_use",
    "detail": "WebSocket command ID is already in flight",
    "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
  }
}

subscription_not_found

{
  "id": 4,
  "type": "error",
  "msg": {
    "code": "subscription_not_found",
    "detail": "subscription is not active on this connection",
    "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef",
    "sid": 9
  }
}

subscription_not_ready

{
  "id": 4,
  "type": "error",
  "sid": 7,
  "msg": {
    "code": "subscription_not_ready",
    "detail": "subscription has not established current state",
    "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
  }
}

snapshot_in_progress

{
  "id": 4,
  "type": "error",
  "sid": 7,
  "msg": {
    "code": "snapshot_in_progress",
    "detail": "subscription already has a snapshot command in flight",
    "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
  }
}

channel_unavailable

{
  "id": 4,
  "type": "error",
  "msg": {
    "code": "channel_unavailable",
    "detail": "current market data is unavailable",
    "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
  }
}

capacity_exceeded

{
  "id": 4,
  "type": "error",
  "msg": {
    "code": "capacity_exceeded",
    "detail": "WebSocket connection command capacity is exhausted",
    "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef",
    "scope": "connection",
    "resource": "in_flight_commands",
    "limit": 32
  }
}

rate_limit_exceeded

{
  "id": 4,
  "type": "error",
  "msg": {
    "code": "rate_limit_exceeded",
    "detail": "member read rate limit is exhausted",
    "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef",
    "retry_after_ms": 1200
  },
  "rate_limit": {
    "bucket": "read",
    "capacity": 30,
    "refill_tokens_per_minute": 900,
    "remaining": 0,
    "full_after_ms": 2000
  }
}

admission_unavailable

{
  "id": 4,
  "type": "error",
  "msg": {
    "code": "admission_unavailable",
    "detail": "shared WebSocket admission is temporarily unavailable",
    "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
  }
}

internal_error

{
  "id": 4,
  "type": "error",
  "msg": {
    "code": "internal_error",
    "detail": "WebSocket command failed",
    "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
  }
}