Skip to content

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 Connection: EIP-712 signature-based connection authentication
  • Mixed Operations: Read operations use connection auth, write operations use per-request signatures
  • 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 Patterns

The Trade WebSocket uses two different authentication patterns depending on the operation:

OperationPatternDetails
Connection authStringified typed dataparams.message contains JSON.stringify({types, domain, primaryType, message}) with a raw hex params.signature
Trading operationsFlat params with signature objectAll fields (subAccountId, orders, nonce, etc.) go directly inside params, with signature: {v, r, s} as a nested object

Connection authentication (method: "auth") sends the entire EIP-712 structure as a JSON-stringified string in params.message, paired with a raw hex signature string.

Trading operations (method: "post") use flat parameters with the signature split into {v, r, s} components. See WebSocket Authentication for the connection auth flow and Place Orders for an example of the trading pattern.

Authentication

Authentication is required immediately after connecting to the Trade WebSocket endpoint. See WebSocket Authentication for complete authentication flow and examples.

Quick Summary:
  1. Connect to wss://papi.synthetix.io/v1/ws/trade
  2. Send authentication message with EIP-712 signature
  3. Receive authentication confirmation with subAccountId
  4. Begin trading operations
Key Points:
  • Uses EIP-712 typed data signing
  • Timestamp must be within ±60 seconds of server time
  • Authentication establishes which subaccount you're trading with
  • Connection remains authenticated until disconnected

Security

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

Comparison with REST

FeatureWebSocketREST
LatencyLower (~10-50ms)Higher (~50-200ms)
ConnectionPersistentPer-request
Real-time UpdatesYesNo (polling required)
OverheadMinimalHTTP headers each request
ComplexityHigherLower
Best ForActive tradingOccasional trades

Available Methods

Order Management

Account Management

Delegation

Data Queries

Authentication & Setup

Related Resources