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.
timestampis the request's Unix epoch in seconds;keyis 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.
Links
- 📖 Full API Documentation: https://docs.truemarkets.co/
- 📧 Support: [email protected]
/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
- Need help? Ask us on Discord, or email [email protected].
- See what changed in the changelog