WebSocket reference

The Match WebSocket API delivers real-time auction state and account updates over a persistent connection. All monetary values in WebSocket events are integer cents, not the REST Money object. For example, $10.00 is represented as 1000.

Connection

Connect by sending a WebSocket upgrade request to the appropriate endpoint.

Environment	Endpoint
Production	`wss://api.circle.com/v1/match/ws`
Sandbox	`wss://api-sandbox.circle.com/v1/match/ws`

Include both of the following protocol values in the Sec-WebSocket-Protocol header of the upgrade request:

circle-match.v1
ticket.<jwt>: replace <jwt> with the ticket token from POST /v1/match/ws/ticket

Authentication

Obtain a WebSocket ticket before opening the connection. Endpoint: POST /v1/match/ws/ticket No request body is required. The response contains a short-lived, single-use token:

{
  "data": {
    "ticket": "eyJ..."
  }
}

Obtain the ticket immediately before opening the socket. The server validates the ticket during the upgrade handshake. An invalid, expired, or missing ticket returns HTTP 401 and the connection is not established.

Session frames

The server sends the following session-level frames to the client.

Frame type	When sent	Fields
`hello`	Immediately after a successful upgrade	`type: "hello"`, `entityId` (string), `serverTime` (ISO 8601)
`keepalive`	Periodically while connected	`type: "keepalive"`, `serverTime` (ISO 8601)
`subscribed`	After a subscribe message is acknowledged	`type: "subscribed"`, `channel` (`"market"` or `"account"`)
`error`	On an invalid subscription or authentication error	`type: "error"`, `channel` (string or null), `error` (string)

Client messages

Send subscribe messages to the server after receiving the hello frame. You can subscribe to multiple channels in a single session.

Message type	Fields	Notes
`subscribe`	`type: "subscribe"`, `channel` (`"market"` or `"account"`)	Send after `hello`. Multiple subscribe messages are allowed.

Market channel

The market channel is public and delivers real-time auction state. Subscribe:

{ "type": "subscribe", "channel": "market" }

Market channel events

Event type	When sent	Key fields
`snapshot`	On subscribe	All fields listed in the market channel fields table
`auction_opened`	A new auction cycle starts	`auctionId`, `lockAt` (ISO 8601), `clearAt` (ISO 8601), `auctionIntervalNs` (integer, nanoseconds)
`auction_locked`	Lock window opens	`auctionId`, `phase: "locked"`
`auction_cleared`	Auction clears	`auctionId`, `clearingFeeBps` (string or null if no match), `matchedSizeCents` (integer cents)
`indicative_updated`	Periodically during the open phase	`indicativeFeeBps` (string or null), `matchableSizeCents` (integer cents), `netImbalanceCents` (integer cents)

Market channel fields

The following fields are present on the snapshot event and on most market events. For background on auction phases and clearing, see How Match works.

Field	Type	Description
`phase`	string	Current auction phase: `"open"`, `"locked"`, or `"settling"`
`indicativeFeeBps`	string or null	Indicative clearing fee in basis points; null if no indicative match exists
`matchableSizeCents`	integer	Volume (in cents) that would match at the indicative fee
`netImbalanceCents`	integer	Net imbalance in cents; negative values indicate burn side exceeds mint side
`mintTotalCents`	integer	Total mint-side volume in cents
`burnTotalCents`	integer	Total burn-side volume in cents
`lockAt`	string	ISO 8601 timestamp when the lock window opens
`clearAt`	string	ISO 8601 timestamp when the auction clears
`lastClearResult`	object or null	Result from the last cleared auction; null if no prior auction has cleared

`lastClearResult` fields

Field	Type	Description
`auctionId`	integer	Identifier for the last cleared auction
`clearingFeeBps`	string or null	Clearing fee in basis points; null if no orders matched
`matchedSizeCents`	integer	Total matched volume in cents

Account channel

The account channel is private and scoped to the authenticated entity. It requires a valid ticket. Subscribe:

{ "type": "subscribe", "channel": "account" }

Account channel events

Event type	When sent	Key fields
`account_snapshot`	On subscribe	Current open orders, available balance, reserved balance, total balance
`order_received`	A new order is accepted	`orderId` (UUID), `status: "pending"`, `orderType`, `amount` (integer cents), `feeBps` (string or null), `postFillAction`
`order_modified`	An order’s fee is modified	`orderId`, `feeBps` (string or null)
`order_canceled`	A single order is cancelled	`orderId`, `status: "cancelled"`
`order_canceled_all`	A cancel-all request completes	`orderIds` (array of UUIDs), `auctionId`
`account_cleared`	An auction clears with activity for this account	`fills` (array), `forwardOrders` (array), `feesRebatedCents` (signed integer)

`account_cleared` fields

Field	Type	Description
`fills`	array	One fill object per matched order. Each fill contains: `orderId`, `filledAmountCents`, `unfilledAmountCents`, `clearingFeeBps`, `matchedAt`
`forwardOrders`	array	Orders rolled into the next auction, resulting from a `roll` post-fill action
`feesRebatedCents`	signed integer	Net rebate or fee for the auction. Positive: net rebate received (mint side). Negative: net fee paid (burn side). Zero: no fills.

Reconnection

Tickets are single-use and cannot be reused after the connection opens. When a connection drops:

Obtain a new ticket using POST /v1/match/ws/ticket.
Open a new WebSocket connection with the new ticket.
Re-send your subscribe messages.

The server delivers a fresh snapshot on re-subscribe. Events that occurred during the disconnection are not replayed. If the auction cleared while you were disconnected, the account_cleared event for that auction is not delivered. Use GET /v1/match/orders to reconcile any fills you may have missed.

Mint

Match

StableFX

Digital Asset Accounts

End User Onboarding

Connection

Authentication

Session frames

Client messages

Market channel

Market channel events

Market channel fields

`lastClearResult` fields

Account channel

Account channel events

`account_cleared` fields

Reconnection

​Connection

​Authentication

​Session frames

​Client messages

​Market channel

​Market channel events

​Market channel fields

​lastClearResult fields

​Account channel

​Account channel events

​account_cleared fields

​Reconnection

Connection

Authentication

Session frames

Client messages

Market channel

Market channel events

Market channel fields

`lastClearResult` fields

Account channel

Account channel events

`account_cleared` fields

Reconnection