WebSocket

Connect to wss://api.testnet.arcus.xyz/v1/ws (mainnet: wss://api.arcus.xyz/v1/ws). The connection multiplexes channel subscriptions and request/response (RPC) calls.

Recommended client resources. For a client consuming the real-time feeds, we recommend at least 2 CPU cores and 4 GB of RAM so message parsing and local book maintenance keep up under load. High-throughput clients (many markets or deep order books) should provision more.

Message envelopes

Subscribe / unsubscribe:

{ "type": "subscribe",   "channel": "<channel_name>", "id": "<subscription_id>" }
{ "type": "unsubscribe", "channel": "<channel_name>", "id": "<subscription_id>" }

The server replies with { "type": "subscribed", ... } and then streams { "type": "channel_data", ... } updates. Each update carries the channel, the subscription id (for per-market channels), and a contents payload. Timestamps are inside contents (e.g. timestamp, epoch, markEpochNanos); there is no top-level publish timestamp. Request / response: every post and get message must include a numeric id chosen by the client. The server echoes the same id in its response. IDs do not need to increase — uniqueness among in-flight calls on the connection is sufficient.

{
  "type": "get",
  "id": 2,
  "request": {
    "type": "l2orderbook",
    "payload": { "market": "BTC-USD" }
  }
}

See Authentication for the signing rules that apply to order methods.

Placing orders

Order methods are asynchronous. The server returns 202 with status: "ACK" (or CANCEL_ACKNOWLEDGED); subscribe to the orders or userFills channels to observe the lifecycle.

{
  "type": "post",
  "id": 1,
  "request": {
    "type": "placeOrder",
    "payload": {
      "address": "0x...",
      "accountIndex": 0,
      "marketId": 1,
      "orderSide": "BUY",
      "orderType": "LIMIT",
      "timeInForce": "GTT",
      "goodTilTime": "4102444800000000",
      "quantity": "0.01",
      "price": "50000"
    },
    "apiKey": "<64-hex-public-key>",
    "timestamp": "1712345678000000000",
    "signature": "<128-hex-signature>"
  }
}

Server response:

{
  "method": "placeOrder",
  "id": 1,
  "status": 202,
  "result": { "orderId": "...", "status": "ACK" }
}

No cancel-on-disconnect. Dropping a WebSocket connection tears down your subscriptions but does not cancel your resting orders — Arcus has no cancel-on-disconnect or dead-man’s-switch. An order rests until it fills, you explicitly cancel it, or its goodTilTime expires, and goodTilTime must be at least ~1 month out (enforced on every order, including IOC/FOK). If your strategy depends on orders being pulled when your process dies, run your own external kill-switch that cancels on disconnect.

Channels

See the Channels reference for the full list and per-channel payload schemas.

Sequence numbers

Streamed messages carry sequence numbers so you can order events, detect dropped messages, and resync after a reconnect. Three scopes exist:

Global — one monotonic counter across the whole exchange, incremented for every event the matching engine processes. Use it to order events across markets and to tell whether you’ve missed anything.
Per-market — a counter local to a single market.
Per-account — a counter local to a single account.

Which field carries the sequence depends on the message:

Scope	Field	Appears on
Global	`globalSequenceId`	`l2Orderbook`, `l2OrderbookUpdates`
Global	`sequenceNumber`	`trades`
Per-market (order book)	`lastSequenceId`	`l2Orderbook`, `l2OrderbookUpdates`
Per-market (market attributes)	`marketSequenceNum`	`exchangeAttributeUpdates` (`marketAttributes` entries)
Per-account	`sequenceNum`	`AccountUpdate` (REST schemas expose the same value as `accountSequenceNum`)

Resyncing the order book

For l2Orderbook, the snapshot’s lastSequenceId is the per-market sequence of the last update it reflects. Apply only l2OrderbookUpdates deltas whose lastSequenceId is greater than the snapshot’s — they’re monotonic and continuous, so a gap means you missed a delta and should re-subscribe for a fresh snapshot. Use globalSequenceId to order order-book events against other markets.

Errors

Responses include an HTTP-like status and either a result or an error object with type, message, and optional field details.

API documentation

Endpoints

Changelog

WebSocket

Message envelopes

Placing orders

Channels

Sequence numbers

Resyncing the order book

Errors

​Message envelopes

​Placing orders

​Channels

​Sequence numbers

​Resyncing the order book

​Errors

Message envelopes

Placing orders

Channels

Sequence numbers

Resyncing the order book

Errors