Trade WebSocket

The Trade WebSocket provides authenticated, real-time access to trading operations with lower latency than REST endpoints.

Endpoint

ws.send() wss://api.synthetix.io/v1/ws/trade

Features

• Low Latency Trading: Submit orders with minimal delay
• Real-time Updates: Instant order status notifications
• Persistent Connection: Single connection for all operations
• Authenticated: Secure EIP-712 signature-based access
• Bidirectional: Request-response and server-pushed updates

Connection Flow

1. Establish Connection: Connect to WebSocket endpoint
2. Authenticate: Send authentication message with signature
3. Trade: Send trading commands using method: "post"
4. Subscribe: Receive real-time updates
5. Maintain: Send heartbeats to keep connection alive

Authentication

Authentication is required immediately after connection. Requests use JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "id": "auth-1",
  "method": "post",
  "params": {
    "action": "authenticate",
    "subAccountId": "1867542890123456789",
    "nonce": 1704067200000,
    "signature": {
      "v": 27,
      "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
    }
  }
}

EIP-712 Domain: { "name": "Synthetix", "version": "1", "chainId": 1, "verifyingContract": "0x0000000000000000000000000000000000000000" }

Authentication Response

Success:

{
  "jsonrpc": "2.0",
  "id": "auth-1",
  "result": {
    "status": "ok",
    "response": {
      "authenticated": true,
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7D1333D6E2"
    },
    "requestId": "5ccf215d37e3ae6d",
    "timestamp": 1704067200000
  }
}

Failure:

{
  "jsonrpc": "2.0",
  "id": "auth-1",
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "Invalid signature",
    "data": null
  }
}

Security

• Secure private key storage
• WSS encrypted connections
• Re-authentication on connection drops
• Server response validation

Comparison with REST

Available Methods

Order Management

• Place Orders - Standard order placement
• Modify Order - Single order modification
• Cancel Orders - Selective order cancellation

Account Management

• Update Leverage - Dynamic leverage adjustment

Data Queries

• Get Orders - Query order history
• Get Positions - Query positions

Authentication & Setup

• Authentication - Detailed auth implementation
• Timeouts & Heartbeats - Connection management

Alternative

• REST Alternative - REST API for comparison