For AI agents: the documentation index is at /llms.txt, and this page is available as Markdown at /api/websocket/institutional.md.

Exchange WebSocket

Overview

This API allows clients to interact with the CeFi trading platform for real time instrument, market data and exchange transactions.

Operations are described from the server's side: send is a message the server sends to you, and receive is a message you send to the server.

Authentication

Authenticated requests carry their credentials in the subscription message payload (not HTTP headers), signed with an ES256 (EC P-256) API key created at app.truemarkets.co. Only the public key is held server-side.

The signed payload is timestamp + TRUEXWS + key + path, where path is the WebSocket endpoint path — use the canonical /v1/cefi/market; the legacy /api/v1 is also accepted but deprecated. The server accepts either, regardless of the host or URL you connect through.

The connection itself takes no credentials: authenticate by sending a signed SUBSCRIBE or UNSUBSCRIBE with key, timestamp and signature. A connection that starts unauthenticated is upgraded by its first signed request.

ES256

Sign the payload with the key's EC P-256 private key (ECDSA over SHA-256) and send the raw 64-byte r || s as base64url without padding. DER-encoded signatures are not accepted.

  • timestamp is the request's Unix epoch in seconds; key is the ES256 API key id.
  • Example payload: 1700000000TRUEXWS11112222-3333-4444-8555-666677778888/v1/cefi/market
  • A key whose account is not enabled for CeFi trading (no bound client_id) is rejected.

Unauthenticated requests

Use type SUBSCRIBE_NO_AUTH or UNSUBSCRIBE_NO_AUTH with only a timestamp, and leave out organization_id, key and signature. Unauthenticated subscriptions are rate limited and coalesced to a fixed publish rate. They are only valid on unauthenticated connections: once a connection is authenticated, no-auth requests are rejected and do not change its subscriptions.

Timestamps

Every subscription request (authenticated or not) carries a timestamp: a UTC Unix epoch in whole seconds. The server accepts timestamps between 15 seconds in the past and 1 second in the future relative to server UTC time; anything outside that window is rejected with an ERROR confirmation.

The 1-second future allowance exists because whole-second timestamps are coarse: a client clock that rounds up to the next second reads ahead of the server's truncated clock even when both are perfectly synchronized. To avoid timestamp rejects:

  • Keep your clock synchronized via NTP; a clock more than ~1 second fast (or ~15 seconds slow) will cause rejects.
  • Truncate (round down) the current time to whole seconds rather than rounding to nearest or up.
  • Generate the timestamp (and signature) immediately before sending — not when the request is queued or built for retry.
  • On a timestamp reject, retry with a freshly generated timestamp and signature.

Unauthenticated Endpoints

Many endpoints have an unauthenticated version which only requires the user to supply a valid timestamp (no older than 15 seconds and at most 1 second in the future, relative to server UTC time). These endpoints batch updates and publish on an interval set by the exchange, typically 1 second.

Authenticated-Only Channels

Some channels require authentication and cannot be accessed without valid credentials:

  • DROPCOPY: Order drop copy channel that provides real-time order state updates.

Heartbeats

A quiet book (no order activity) sends nothing after its snapshot, which a client cannot tell apart from a dead connection unless it can see WebSocket protocol pings (browsers cannot). Heartbeats are opt-in: include HEARTBEAT in channels of a SUBSCRIBE or SUBSCRIBE_NO_AUTH request (item_names is ignored for it, and it can share a request with other channels). The confirmation then lists HEARTBEAT among the subscriptions.

Once subscribed, the connection receives a HEARTBEAT message only after 10 seconds with nothing else sent to it; any other message resets that clock, so an active feed never carries heartbeats. Treat ~30 seconds of total silence as a dead connection and reconnect. Unsubscribe with UNSUBSCRIBE/UNSUBSCRIBE_NO_AUTH on the HEARTBEAT channel.

/v1/cefi/market

Subscribe

SEND Message sent to server indicating what channels and data the user would like to subscribe to. Message reference

Welcome

RECEIVE Message received when connecting to the server and establishing a websocket connection. Message reference

Heartbeat

RECEIVE Message sent to a connection subscribed to the HEARTBEAT channel after 10 seconds with nothing else sent to it, so clients can tell a quiet feed from a dead connection. Message reference

Confirmation

RECEIVE Message sent from server containing channels and items the user is currently subscribed to. Message reference

Instrument

RECEIVE Message sent from server with instrument data. Message reference

Trade

RECEIVE Message sent from server containing the latest trade information for a subscribed instrument. Message reference

Ebbo

RECEIVE Message sent from server containing the latest exchange best bid and offer information for a subscribed instrument. Message reference

Depth

RECEIVE Message sent from server containing the latest market data change for a subscribed instrument. Message reference

Auction

RECEIVE Message sent from server containing the latest opening-auction indicative for a subscribed instrument. A status of INVALID indicates the instrument is not currently in an opening auction; updates are emitted while an auction is in progress, plus one final zeroed update (status INVALID) when the auction completes. Message reference

Index

RECEIVE Message sent from server with the exchange's own view of a subscribed price index after each one-second bar applies: the bar, the feed state, and the settlement value on the bar that closes a settlement window. An up/down outcome market opens at the settlement value of the window ending at its open time (its strike) and resolves YES when the settlement value of the window ending at its expiry is strictly above it, so a client can check a verdict from this stream rather than trust it. Items are observable ids as strings; an outcome instrument's terms.resolver_id names its observable. Message reference

Dropcopy

RECEIVE Message sent from server containing order drop copy data for subscribed client IDs. Provides real-time order state updates including new orders, fills, cancellations, and modifications. Requires authentication - unauthenticated connections will be rejected. A DROPCOPY subscription placed while the exchange is still syncing its client catalog (shortly after a restart) receives a confirmation without that subscription and a message asking you to retry — resend the subscription in a few moments. Message reference

Was this page helpful?YesNo