WebSocket Reference

Address fields refer to the wallet the user trades from.

Base URL:

wss://markets.hit.com

Connect with transports: ["websocket"]. The server accepts the websocket transport only, on both namespaces, so a client left on the Socket.IO default — which opens with HTTP long-polling — is refused. For /user API key signatures, see Developer Authentication.

Namespaces

`/`

Authentication: Public Public order book and event data.

`/user`

Authentication: API key HMAC User-specific balances, positions, orders and trades.

Public Client Messages

Event	Payload type	Description
`ping`	`PingPayload`	Health check.
`orderbook-market-connect`	`OrderbookTokenIds`	Subscribe to outcome token IDs.
`orderbook-market-disconnect`	`OrderbookTokenIds`	Unsubscribe from outcome token IDs.
`event-connect`	UUID string or omitted	Subscribe to an event UUID, or all event updates when omitted.
`event-disconnect`	UUID string or omitted	Unsubscribe from an event UUID, or the all-events subscription when omitted.
`crypto-price-connect`	string[]	Subscribe to allowlisted lowercase crypto symbols, such as `btcusdt`.
`crypto-price-disconnect`	string[]	Unsubscribe from crypto symbols.

PingPayload:

Field	Type	Required	Description
none	object	No	Send an empty object.

orderbook-market-connect

Authentication: Public Subscribe to one or more outcome token IDs. Use the market tokenId1 and tokenId2 values from market data when you want both sides of a binary market. Payload type: OrderbookTokenIds.

[
  "66539633449217268141320411658481757807854020589069449399851604049177251401512"
]

Socket.IO example:

socket.emit("orderbook-market-connect", [
  "66539633449217268141320411658481757807854020589069449399851604049177251401512",
]);

On subscribe, the backend joins one order book room per token ID and requests an initial snapshot for each token. Successful snapshots are emitted on orderbook as an OrderBook[]. Live level changes are emitted later on orderbook-price-change. If an initial snapshot cannot be loaded because of a transient backend failure, the server emits orderbook-error with the affected tokenIds. Unknown token IDs may produce no snapshot and no error. Two per-socket limits apply to this message, and both answer with an orderbook-error rather than dropping your message silently:

At most 20 orderbook-market-connect messages per 10 seconds. A message over that rate is dropped before it is parsed and answered with reason: "rate_limited", carrying maxMessages and windowMs and an empty tokenIds. Resend it once the window has passed.
At most 500 distinct token subscriptions held at once (configurable, and the same number as the per-message cap). A message that would take you past it is rejected in full and answered with reason: "subscription_limit_reached", carrying maxTokenIds and a sample of your token IDs. Token IDs you already hold do not count against it. Send orderbook-market-disconnect for books you no longer need, then resend.

Unsubscribe from Token Order Books

orderbook-market-disconnect

Authentication: Public Stop receiving order book snapshots and deltas for one or more outcome token IDs. Payload type: OrderbookTokenIds.

[
  "66539633449217268141320411658481757807854020589069449399851604049177251401512"
]

Socket.IO example:

socket.emit("orderbook-market-disconnect", [
  "66539633449217268141320411658481757807854020589069449399851604049177251401512",
]);

The backend does not emit a dedicated unsubscribe confirmation event. OrderbookTokenIds:

Field	Type	Required	Description
none	string[]	Yes	Array of outcome token IDs.

Public Server Events

Event	Payload type	Description
`pong`	`PongPayload`	Ping response.
`app-error`	`AppError`	WebSocket error frame.
`orderbook`	`OrderBook[]`	Order book snapshot.
`orderbook-price-change`	`OrderBookPriceChange`	Price level delta.
`orderbook-error`	`OrderBookError`	Snapshot failure, or a refused subscribe. Branch on `retryable`.
`event-onchain-update`	`EventOnchainUpdatePublic` or `EventOnchainUpdateRaw`	On-chain event or market update.
`tick-size-change`	`TickSizeChange`	Market tick size update.
`order-speed-bump-pending`	`OrderSpeedBumpPending`	Order delayed before matching.
`crypto-price`	`CryptoPrice`	Live crypto price tick.
`crypto-price-history`	`CryptoPriceHistory`	Initial crypto price history after subscribing.
`crypto-price-error`	`CryptoPriceError`	Subscription failure, or a refused subscribe. Not always per-symbol.
`global-trade`	`GlobalTrade`	Site-wide confirmed trade feed. Broadcast automatically.
`event-trade`	`GlobalTrade`	Confirmed trade for an event joined with `event-connect`.
`live-volume`	`LiveVolume`	Coalesced absolute market and event volume updates. Broadcast automatically.

PongPayload:

Field	Type	Required	Description
none	object	No	Empty object.

AppError:

Field	Type	Required	Description
`message`	string or object	Yes	Error message or structured WebSocket exception payload.

OrderBook:

Field	Type	Required	Description
`market`	UUID string	Yes	Market UUID.
`asset_id`	string	Yes	Outcome token ID.
`hash`	string	Yes	Book state hash.
`timestamp`	integer	Yes	Book timestamp.
`bids`	`OrderBookLevel[]`	Yes	Bid price levels.
`asks`	`OrderBookLevel[]`	Yes	Ask price levels.
`tick_size`	string	Yes	Minimum price increment.

OrderBookLevel:

Field	Type	Required	Description
`price`	string	Yes	Price level.
`size`	string	Yes	Available size at the level.

OrderBookPriceChange:

Field	Type	Required	Description
`asset_id`	string	Yes	Outcome token ID.
`market`	UUID string	Yes	Market UUID.
`changes`	`OrderBookPriceLevel[]`	Yes	Changed price levels.
`timestamp`	string	Yes	Delta timestamp.
`hash`	string	Yes	Book state hash after the delta.
`tick_size`	string	Yes	Minimum price increment.

OrderBookPriceLevel:

Field	Type	Required	Description
`price`	string	Yes	Price level.
`side`	enum string	Yes	`buy` or `sell`.
`size`	string	Yes	New size at the level.

OrderBookError:

Field	Type	Required	Description
`tokenIds`	string[]	Yes	The token IDs the frame concerns. Empty when nothing was parsed, and a bounded sample of your request on the two cap refusals.
`reason`	enum string	Yes	One of `snapshot_unavailable`, `too_many_tokens`, `invalid_payload`, `rate_limited` or `subscription_limit_reached`.
`retryable`	boolean	Yes	Whether resending the same message can succeed.
`maxTokenIds`	integer	No	The token limit that applied. Present on `too_many_tokens` and `subscription_limit_reached`.
`distinctCount`	integer	No	Distinct token IDs you sent, after duplicates collapse. Present on `too_many_tokens` when you exceeded the configurable cap.
`receivedCount`	integer	No	Raw element count, before duplicates collapse. Present on `too_many_tokens` when you exceeded the fixed structural ceiling of 10000. Never present alongside `distinctCount`.
`expected`	string	No	What a valid payload looks like. Present on `invalid_payload`.
`maxMessages`	integer	No	Messages allowed per window. Present on `rate_limited`.
`windowMs`	integer	No	Length of that window in milliseconds. Present on `rate_limited`.

Branch on retryable before reason. retryable: false means resending the same message fails identically — change it rather than retry it. snapshot_unavailable, rate_limited and subscription_limit_reached are retryable; too_many_tokens and invalid_payload are not. Treat an unrecognised reason as transient only when retryable is true. EventOnchainUpdatePublic:

Field	Type	Required	Description
`event_type`	enum string	Yes	`event_onchain_update`.
`eventId`	UUID string	Yes	Event UUID.
`marketId`	UUID string	Yes	Market UUID.
`status`	enum string	Yes	`proposed` or `resolved`.
`timestamp`	integer	No	Block timestamp.

EventOnchainUpdateRaw:

Field	Type	Required	Description
`eventId`	UUID string	Yes	Event UUID.
`marketId`	UUID string	Yes	Market UUID.
`ancillaryData`	string	Yes	UMA ancillary data.
`status`	enum string	Yes	`initialized`, `registered`, `proposed`, `resolved`, `disputed`, `settled` or `paused`.
`from`	boolean	Yes	Previous on-chain boolean state.
`to`	boolean	Yes	New on-chain boolean state.
`blockTimestamp`	integer	No	Block timestamp.

TickSizeChange:

Field	Type	Required	Description
`event_type`	enum string	Yes	`tick_size_change`.
`market`	UUID string	Yes	Market UUID.
`old_tick_size`	string	Yes	Previous tick size.
`new_tick_size`	string	Yes	New tick size.
`timestamp`	integer	Yes	Event timestamp.

OrderSpeedBumpPending:

Field	Type	Required	Description
`market`	UUID string	Yes	Market UUID used as the subscription key.
`orderId`	UUID string	No	Delayed order UUID when supplied by the producer.
additional fields	object	No	The backend forwards any additional producer fields unchanged.

CryptoPrice:

Field	Type	Required	Description
`symbol`	string	Yes	Lowercase market symbol.
`price`	string	Yes	Latest price.
`timestamp`	integer	Yes	Source timestamp in milliseconds.
`source`	enum string	No	`BINANCE` or `PYTH`.

CryptoPriceHistory:

Field	Type	Required	Description
`symbol`	string	Yes	Lowercase market symbol.
`points`	`{ price: string, timestamp: integer }[]`	Yes	Oldest-first price history.
`stale`	boolean	Yes	Whether the source history may no longer be live.
`source`	enum string	No	`BINANCE` or `PYTH`.

CryptoPriceError has two shapes, and they do not carry the same fields:

`reason`	Fields	When
`subscribe_failed`	`symbol`, `reason`	One symbol’s subscription failed. No `retryable` on this shape.
`rate_limited`	`reason`, `retryable: true`, `maxMessages`, `windowMs`	Your socket sent more than 20 `crypto-price-connect` messages in 10 seconds. No `symbol`, because nothing was parsed. Resend once the window has passed.

A crypto-price-connect whose payload is invalid — not an array, empty, more than 20 symbols, or a symbol longer than 32 characters — is ignored with no frame at all, as is a symbol that is not on the allowlist. Only the rate breach is answered. GlobalTrade uses the TradeActivity shape, including anonymous and marketDisplayName. event-trade uses the same payload as global-trade, but is emitted only to the room for the trade’s parent event. Send event-connect with that event UUID to receive it. LiveVolume:

Field	Type	Required	Description
`markets`	`{ id: UUID string, v: string }[]`	Yes	Absolute all-time USDC volume for changed markets.
`events`	`{ id: UUID string, v: string }[]`	Yes	Absolute all-time USDC volume for changed events.

User Client Messages

Event	Payload type	Description
`user-connect`	`UserConnectPayload`	Authenticate and subscribe to the user channel.
`user-disconnect`	empty object	Unsubscribe from the user channel.
`initial-data`	empty object	Request initial collateral balances.
`initial-shares-by-market`	UUID string	Retired. No longer handled, so the server sends no reply. Use `user-positions-update` and `GET /api/v1/markets/user-positions`.
`shares-by-market-disconnect`	empty object	Retired. No longer handled.

UserConnectPayload:

Field	Type	Required	Description
`auth`	`TradingApiKeyAuth`	Yes	API key WebSocket auth payload.

TradingApiKeyAuth:

Field	Type	Required	Description
`apiKey`	string	Yes	API key identifier.
`signature`	string	Yes	HMAC-SHA256 signature.
`timestamp`	string	Yes	Unix timestamp in milliseconds.
`passphrase`	string	Yes	API passphrase.

User Server Events

Event	Payload type	Description
`user-authenticated`	`UserAuthenticated`	Authentication result.
`app-error`	`AppError`	WebSocket error frame.
`collateral-balance`	`BalanceUpdate`	Wallet collateral balance.
`collateral-balance-eoa`	`BalanceUpdate`	Retired. No longer emitted. Use `collateral-balance`.
`shares-by-market-update`	—	Retired. No longer emitted. Use `user-positions-update`.
`user-positions-update`	`UserPositionUpdate`	Position update.
`user-order`	`UserOrderEvent[]`	Order update.
`user-trade`	`TradeEvent[]`	Trade update.
`user-reward-claim-update`	`RewardClaimUpdate`	Rewards claim dispatch notification.
`transaction`	`TransactionUpdate`	Transaction status update.

UserAuthenticated:

Field	Type	Required	Description
`success`	boolean	Yes	Whether authentication succeeded.
`error`	string	No	Failure reason.

BalanceUpdate:

Field	Type	Required	Description
`value`	string	Yes	Token balance.

UserPositionUpdate:

Field	Type	Required	Description
`tokenId`	string	Yes	Outcome token ID.
`amount`	string	Yes	Updated token amount.
`acquisitionPrice`	number	Yes	Acquisition price. `0` when no cost basis is recorded for the position: read it as unknown, not as free.
`timestamp`	string (date-time)	Yes	Update timestamp.

Binding events to your orders

Bind an event to your order by its hash rather than by matching price and size: two orders with the same shape are indistinguishable that way. If you sign your own orders, you can compute the hash locally before you submit, while id is server-minted and only reaches you with the HTTP response — which the first event for that order often precedes. Three gaps make the hash the only reliable link:

A maker’s fill produces no user-order event. Only the taker is notified on a match, so as a maker you learn of your fill from user-trade and bind it through maker_orders[].order_hash.
A fully filled order produces no terminal user-order event. Its last event is user-trade.
Only GTC orders produce user-order events, apart from a REJECTION. The only event naming a FOK or FAK order is user-trade, or a REJECTION. Because a liquidation is now a CANCELLATION rather than a REJECTION, it no longer takes that exception — so do not rely on a frame arriving for every order the platform removes. Reconcile against GET /orders instead.

UserOrderEvent:

Field	Type	Required	Description
`event_type`	enum string	Yes	`order`.
`asset_id`	string	Yes	Outcome token ID.
`associate_trades`	string[] or null	Yes	Associated trade IDs. Currently `null`.
`id`	UUID string	Yes	Order UUID.
`hash`	string	Yes	EIP-712 order hash: lowercase `0x`-prefixed, 66 characters. The same value as `Order.hash` in the REST API. If you sign orders yourself you can compute it before submitting and use it to bind this event to your order without waiting for the create response. Not the book-state `hash` on the public order-book events.
`market`	UUID string	Yes	Market UUID.
`order_owner`	UUID string	Yes	Order owner user ID.
`original_size`	string	Yes	Submitted order size.
`outcome`	string	Yes	Outcome label.
`owner`	UUID string	Yes	Order owner user ID.
`price`	string	Yes	Order price.
`side`	enum string	Yes	`buy` or `sell`.
`size_matched`	string	Yes	Matched size.
`timestamp`	string	Yes	Order creation timestamp converted to Unix milliseconds string.
`type`	enum string	Yes	`PLACEMENT`, `UPDATE`, `CANCELLATION` or `REJECTION`.
`rejection_reason`	string	No	Present when `type=REJECTION`. Known values include `no_fill_available`, `stale_nonce` and `onchain_revert:{reason}`.
`cancellation_reason`	string	No	Present when `type=CANCELLATION` and the platform cancelled the order, not when you cancelled it. Values written today are `expired` (the order’s `expiration` passed) and `insufficient_balance` (your holdings no longer back it). Treat an unrecognised value as a cancel with no stated reason.

An order removed because your balance no longer backs it is now a CANCELLATION, not a REJECTION. It ends CANCELLED and carries cancellation_reason: "insufficient_balance", where it previously ended REJECTED and carried rejection_reason: "insufficient_balance". If you detect liquidations by watching for REJECTION frames, you will stop detecting them. Both shapes can appear while the release is rolling out, so handle each until it completes.

TradeEvent:

Field	Type	Required	Description
`event_type`	enum string	Yes	`trade`.
`asset_id`	string	Yes	Outcome token ID.
`id`	UUID string	Yes	Trade UUID.
`last_update`	string	Yes	Last update timestamp converted to Unix milliseconds string.
`maker_orders`	`TradeMakerOrder[]`	Yes	Maker orders that filled the trade.
`market`	UUID string	Yes	Market UUID.
`match_time`	string	Yes	Match timestamp converted to Unix milliseconds string.
`order_hash`	string	Yes	EIP-712 hash of the order this event is about — the order whose `owner`, `price`, `size` and `side` the event describes. Equals `taker_order_hash` when `trader_side` is `TAKER`, and `maker_orders[0].order_hash` when it is `MAKER`, so you never need to branch on `trader_side` to find your own order.
`outcome`	string	Yes	Outcome label.
`owner`	UUID string	Yes	User ID receiving this event.
`price`	string	Yes	Fill price.
`side`	enum string	Yes	`buy` or `sell`.
`trader_side`	enum string	Yes	`MAKER` or `TAKER`.
`size`	string	Yes	Filled size.
`status`	enum string	Yes	`MATCHED`, `MINED`, `CONFIRMED` or `FAILED`.
`taker_order_id`	UUID string	Yes	Taker order UUID.
`taker_order_hash`	string	Yes	EIP-712 hash of the taker order.
`timestamp`	string	Yes	Emit timestamp converted to Unix milliseconds string.
`trade_owner`	UUID string	Yes	Taker owner user ID.
`type`	enum string	Yes	`TRADE`.

TradeMakerOrder:

Field	Type	Required	Description
`asset_id`	string	Yes	Outcome token ID.
`matched_amount`	string	Yes	Amount matched from this maker order.
`order_id`	UUID string	Yes	Maker order UUID.
`order_hash`	string	Yes	EIP-712 hash of the maker order.
`outcome`	string	Yes	Outcome label.
`owner`	UUID string	Yes	Maker owner user ID.
`price`	string	Yes	Maker fill price.

RewardClaimUpdate:

Field	Type	Required	Description
`userId`	UUID string	Yes	Hit user ID.
`recipientAddress`	address string	No	Claim recipient address.
`claimableMicroUsdc`	string	No	Claimable amount in micro-USDC.
`rowCount`	integer	No	Number of settlement rows included.
`outcome`	enum string	No	`started`, `dispatched` or `error`. `started` marks the claim as in flight. Missing values should be treated as `dispatched`.
`reason`	string	No	Failure reason, such as `signer-missing`, `executor-failed` or `task-error`.

TransactionUpdate:

Field	Type	Required	Description
`event_type`	enum string	Yes	`transaction`.
`txHash`	string	Yes	Transaction hash.
`status`	enum string	Yes	`success` or `failed`.
`operationType`	enum string	No	What finished: `split_position`, `merge_position`, `redeem_position`, `convert_position`, `transfer_usdc`, `wallet_calls`, `wallet_setup` or `wallet_approvals_repair`.
`timestamp`	integer	Yes	Emit timestamp in milliseconds.

Overview

Market Data

Trading

Realtime

Namespaces

`/`

`/user`

Public Client Messages

Unsubscribe from Token Order Books

Public Server Events

User Client Messages

User Server Events

Binding events to your orders

​Namespaces

​/

​/user

​Public Client Messages

​Subscribe to Token Order Books

​Unsubscribe from Token Order Books

​Public Server Events

​User Client Messages

​User Server Events

​Binding events to your orders

Namespaces

`/`

`/user`

Public Client Messages

Subscribe to Token Order Books

Unsubscribe from Token Order Books

Public Server Events

User Client Messages

User Server Events

Binding events to your orders