Trading via WebSocket

Submit orders and other actions through WebSocket using the unified transaction format

All trading operations require Ed25519 signatures and a unique nonce for replay protection. See Transaction Signing for the canonical message format and Place & Cancel Orders for the full transaction envelope.

Post Request Format

All order and trading-related operations use the post method with the unified transaction payload:

{
  "method": "post",
  "request": {
    "type": "action",
    "payload": {
      "actions": [Action, ...],
      "nonce": 1704067200000000000,
      "account": "base58_pubkey",
      "signer": "base58_pubkey",
      "signature": "base58_signature"
    }
  },
  "id": 1
}

Transaction fields:

Field	Description
actions	Array of actions to execute atomically (see Action types below)
nonce	Unique integer (u64) for replay protection (e.g. timestamp in nanoseconds)
account	Account public key (base58) — whose account is being traded
signer	Signer public key (base58) — who is signing (usually same as account, or authorized agent)
signature	Ed25519 signature (base58) over the signed message

Signing: The signed message is bincode_serialize(actions) + nonce_le_u64 + account_pubkey_bytes. Signer is not part of the signed message. See Transaction Signing for details.

---

Action Types

Each action in the actions array is a single-key object. The key is the action tag, the value is the action payload.

Action	Description	Example
l	Limit order	{"l": {"c": "BTC-USD", "b": true, "px": 100000.0, "sz": 0.1, "tif": "GTC", "r": false}}
m	Market order	{"m": {"c": "BTC-USD", "b": true, "sz": 0.1, "r": false}}
mod	Modify order size	{"mod": {"oid": "base58_hash", "symbol": "BTC-USD", "amount": 0.05}}
cx	Cancel one order	{"cx": {"c": "BTC-USD", "oid": "base58_hash"}}
cxa	Cancel all orders	{"cxa": {"c": ["BTC-USD"]}} or {"cxa": {"c": []}} for all symbols

Other actions (faucet, updateUserSettings, agentWalletCreation) use the same post format and are documented on Request Faucet, Update User Settings, and Manage Agent Wallet.

---

Place Limit Order

Request

{
  "method": "post",
  "request": {
    "type": "action",
    "payload": {
      "actions": [
        {"l": {"c": "BTC-USD", "b": true, "px": 100000.0, "sz": 0.1, "tif": "GTC", "r": false}}
      ],
      "nonce": 1704067200000000000,
      "account": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
      "signer": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
      "signature": "5j7s...base58..."
    }
  },
  "id": 1
}

Limit order (l) fields: c (symbol), b (true = buy), px (limit price), sz (size), tif (time in force), r (reduce-only).

Time in force: GTC (good till cancel, rests on book), IOC (immediate or cancel), ALO (add liquidity only / post-only; rejects if would cross).

---

Place Market Order

{
  "method": "post",
  "request": {
    "type": "action",
    "payload": {
      "actions": [
        {"m": {"c": "BTC-USD", "b": true, "sz": 0.1, "r": false}}
      ],
      "nonce": 1704067200000000000,
      "account": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
      "signer": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
      "signature": "5j7s...base58..."
    }
  },
  "id": 2
}

Market order (m) fields: c (symbol), b (true = buy), sz (size), r (reduce-only).

---

Modify Order

Change the size of an existing order:

{
  "method": "post",
  "request": {
    "type": "action",
    "payload": {
      "actions": [
        {"mod": {"oid": "Fpa3oVuL3UzjNANAMZZdmrn6D1Zhk83GmBuJpuAWG51F", "symbol": "BTC-USD", "amount": 0.05}}
      ],
      "nonce": 1704067200000000000,
      "account": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
      "signer": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
      "signature": "5j7s...base58..."
    }
  },
  "id": 3
}

Modify (mod) fields: oid (order ID, base58), symbol, amount (new size).

---

Cancel Order

Request

{
  "method": "post",
  "request": {
    "type": "action",
    "payload": {
      "actions": [
        {"cx": {"c": "BTC-USD", "oid": "Fpa3oVuL3UzjNANAMZZdmrn6D1Zhk83GmBuJpuAWG51F"}}
      ],
      "nonce": 1704067200000000000,
      "account": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
      "signer": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
      "signature": "5j7s...base58..."
    }
  },
  "id": 4
}

---

Cancel All Orders

Cancel all in one or more symbols: use cxa with c = array of symbols.

Cancel all across all symbols: use cxa with c = [].

Cancel all in symbol(s)

{
  "method": "post",
  "request": {
    "type": "action",
    "payload": {
      "actions": [{"cxa": {"c": ["BTC-USD"]}}],
      "nonce": 1704067200000000000,
      "account": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
      "signer": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
      "signature": "5j7s...base58..."
    }
  },
  "id": 5
}

---

Batch Actions

Multiple actions can be combined in a single transaction (same nonce, account, signer, signature). One status is returned per action/event.

Example: cancel one order and place two new limit orders

{
  "method": "post",
  "request": {
    "type": "action",
    "payload": {
      "actions": [
        {"cx": {"c": "BTC-USD", "oid": "old_order_id_base58"}},
        {"l": {"c": "BTC-USD", "b": true, "px": 99900.0, "sz": 0.05, "tif": "GTC", "r": false}},
        {"l": {"c": "BTC-USD", "b": false, "px": 100100.0, "sz": 0.05, "tif": "GTC", "r": false}}
      ],
      "nonce": 1704067200000000000,
      "account": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
      "signer": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
      "signature": "5j7s...base58..."
    }
  },
  "id": 7
}

---

Response Format

Field	Description
type	Always "post" for trading responses
id	Request ID (matches the request)
data.type	Always "action"
data.payload.status	"ok" or "error"
data.payload.response.type	Response type (e.g., "order")
data.payload.response.data.statuses	Array of status objects (one per order)

---

Status Types

Non-Terminal (Order Still Active)

Status	Description	Fields
resting	Order placed and resting on book	{oid}
working	Partial fills, still resting	{oid, filledSz, remainingSz, vwap}

Terminal (Order Complete)

Status	Description	Fields
filled	Order fully filled	{oid, totalSz, avgPx}
partiallyFilled	Partially filled and terminal	{oid, totalSz, avgPx}
cancelled	Cancelled by user	{oid}
cancelledRiskLimit	Cancelled - risk limit	{oid, reason?}
cancelledSelfCrossing	Cancelled - self-crossing (STP)	{oid}
cancelledReduceOnly	Cancelled - would increase position	{oid}
cancelledIOC	IOC expired without full fill	{oid, filledSz}
rejectedCrossing	Post-only rejected for crossing	{oid}
rejectedDuplicate	Duplicate order ID	{oid}
rejectedRiskLimit	Rejected - risk limit	{oid, reason?}
rejectedInvalid	Invalid parameters	{oid, reason?}
deposit	Faucet deposit succeeded	{amount}
agentWallet	Agent wallet registered	{agentWallet}
error	Generic error	{message}

---

Response Examples

Working (partial fill)

{
  "type": "post",
  "id": 1,
  "data": {
    "type": "action",
    "payload": {
      "status": "ok",
      "response": {
        "type": "order",
        "data": {
          "statuses": [{
            "working": {
              "oid": "Fpa3oVuL3UzjNANAMZZdmrn6D1Zhk83GmBuJpuAWG51F",
              "filledSz": 0.05,
              "remainingSz": 0.05,
              "vwap": 100000.0
            }
          }]
        }
      }
    }
  }
}

---

Error Handling

Invalid signature

Ensure you’re using the correct serialization format including nonce. Use official SDKs when possible.

Unauthorized signer

If the signer is different from the account, the signer must be registered as an agent for that account. See Manage Agent Wallet (same transaction envelope, agentWalletCreation action).

Insufficient margin

Check your available balance before placing orders. Consider position size and leverage.

Duplicate nonce

Each nonce can only be used once. Use nanosecond timestamps: BigInt(Date.now()) * 1_000_000n.

Order rejected

Verify order parameters meet market requirements (min size, tick size, etc).