Smart Order Routing WebSocket API

The Smart Order Routing WebSocket API provides authenticated, real-time streaming market data and execution data to authorized Smart Order Routing platform customers. This API uses a bidirectional WebSocket connection for both request-response operations and streaming data delivery.

This API is available only to Smart Order Routing customers on the allow list.

Connection

Endpoints

Production: wss://ws.paxos.com/
Sandbox: wss://ws.sandbox.paxos.com/

Authentication

Authentication is performed during the WebSocket handshake. You must provide valid OAuth2 credentials in the Authorization Bearer header.

You must include the exchange:read_aggregated_marketdata_stream scope. Without this scope, the WebSocket route responds with 403 Forbidden.

➊ Get OAuth2 Credentials

Request an access token using your client credentials:

Sandbox

curl -X POST https://oauth.sandbox.paxos.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id={your_client_id}" \
  -d "client_secret={your_client_secret}" \
  -d "scope=exchange:read_aggregated_marketdata_stream"

Production

curl -X POST https://oauth.paxos.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id={your_client_id}" \
  -d "client_secret={your_client_secret}" \
  -d "scope=exchange:read_aggregated_marketdata_stream"

Response

{
  "access_token": "{your_bearer_token}",
  "expires_in": 3600,
  "token_type": "bearer",
  "scope": "exchange:read_aggregated_marketdata_stream"
}

➋ Establish WebSocket Connection

Use the access token as the Bearer token when establishing the WebSocket connection:

const ws = new WebSocket('wss://ws.sandbox.paxos.com/', {
  headers: {
    'Authorization': 'Bearer {your_bearer_token}'
  }
});

Connection Lifecycle

Client establishes WebSocket connection with authentication
Server maintains connection with automatic ping/pong heartbeat
Client subscribes/unsubscribes to data channels (e.g., BTCUSD market data)
Server streams data to subscribed channels
Connection closes on client disconnect or server shutdown

Quick Start Example

Here’s a minimal example to get you started:

// 1. Connect with authentication
const ws = new WebSocket('wss://ws.sandbox.paxos.com/', {
  headers: { 'Authorization': 'Bearer {your_token}' }
});

// 2. Subscribe to market data on connection
ws.on('open', () => {
  ws.send(JSON.stringify({
    type: 'subscribe',
    channels: [{
      type: 'market_data',
      params: { market: 'BTCUSD' }
    }]
  }));
});

// 3. Handle incoming messages
ws.on('message', (data) => {
  const msg = JSON.parse(data);
  
  if (msg.type === 'subscribe') {
    console.log('Subscription confirmed:', msg.channels[0].success);
  } else if (msg.channel === 'market_data') {
    console.log('Market data:', msg.payload);
  }
});

Operations & Message Formats

Subscribe to one or more data channels for real-time updates. Request:

{
  "type": "subscribe",
  "channels": [
    {
      "type": "market_data",
      "params": {
        "market": "BTCUSD"
      }
    },
    {
      "type": "execution_data",
      "params": {
        "market": "ETHUSD"
      }
    }
  ]
}

Response:

{
  "type": "subscribe",
  "channels": [
    {
      "type": "market_data",
      "params": { "market": "BTCUSD" },
      "success": true
    },
    {
      "type": "execution_data",
      "params": { "market": "ETHUSD" },
      "success": true
    }
  ]
}

The response echoes back the request parameters for each channel, allowing you to correlate which subscription succeeded or failed when subscribing to multiple channels in a single request.

Unsubscribe Operation

Stop receiving updates from specific channels. Request:

{
  "type": "unsubscribe",
  "channels": [
    {
      "type": "market_data",
      "params": {
        "market": "BTCUSD"
      }
    }
  ]
}

Response:

{
  "type": "unsubscribe",
  "channels": [
    {
      "type": "market_data",
      "params": { "market": "BTCUSD" },
      "success": true
    }
  ]
}

The response echoes back the request parameters for each channel, allowing you to correlate which unsubscription succeeded or failed when unsubscribing from multiple channels in a single request.

List Subscriptions Operation

Get all active subscriptions for your connection. Request:

{
  "type": "subscription_list"
}

Response:

{
  "type": "subscription_list",
  "channels": [
    {
      "type": "market_data",
      "params": {
        "market": "BTCUSD"
      }
    },
    {
      "type": "execution_data",
      "params": {
        "market": "ETHUSD"
      }
    }
  ]
}

Data Channels

The Smart Order Routing WebSocket API supports four types of streaming data channels:

Market Data Channel

Provides real-time order book updates with initial snapshots and incremental changes.

Channel type: market_data
Initial message: Full order book snapshot
Subsequent messages: Incremental updates
View detailed documentation →

Example streaming message:

{
  "channel": "market_data",
  "payload": {
    "market": "BTCUSD",
    "type": "UPDATE",
    "time": "2024-01-15T10:30:01.456Z",
    "bids": [{"price": "50000.00", "amount": "1.5"}],
    "asks": [{"price": "50100.00", "amount": "2.0"}]
  }
}

Top of Book Channel

Provides real-time updates of the best bid and best ask prices only.

Channel type: market_data.top_of_book
Message frequency: On best price changes
Lightweight alternative to full order book
View detailed documentation →

Example streaming message:

{
  "channel": "market_data.top_of_book",
  "payload": {
    "market": "BTCUSD",
    "type": "TOP_OF_BOOK",
    "timestamp": "2024-01-15T10:30:00.123456789Z",
    "bids": [{"price": "50000.00", "amount": "1.5"}],
    "asks": [{"price": "50100.00", "amount": "2.0"}]
  }
}

Execution Data Channel

Provides real-time trade execution notifications.

Channel type: execution_data
Message frequency: On each trade execution
View detailed documentation →

Example streaming message:

{
  "channel": "execution_data",
  "payload": {
    "market": "BTCUSD",
    "price": "50000.00",
    "amount": "0.5",
    "executed_at": "2024-01-15T10:30:00.123Z"
  }
}

Heartbeat Channel

Provides logical-level liveness signal for connection monitoring.

Channel type: heartbeat
Message frequency: Periodic heartbeat messages
No parameters required
View detailed documentation →

Example streaming message:

{
  "channel": "heartbeat",
  "payload": {
    "timestamp": "2024-01-15T10:30:00.123456789Z"
  }
}

Error Handling

The API uses standardized error codes:

Error Code	Description
`UNKNOWN_ACTION`	The requested action type is not recognized
`INTERNAL_SERVER_ERROR`	An unexpected server error occurred
`MALFORMED_REQUEST`	The request JSON is invalid or cannot be parsed
`NO_EFFECT_ACTION`	The action would have no effect (e.g., duplicate subscription)
`UNKNOWN_CHANNEL`	The requested channel type is not recognized
`UNKNOWN_CHANNEL_PARAMS_CONFIGURATION`	Invalid or missing channel parameters

Questions? Contact Support.

API Documentation

Deposits and Withdrawals

Address Verification

Identity

Profiles

Sandbox

Orchestrations / Conversions

Taxes

Trading

Rewards

Rewards Engine

Events

API Credentials

Websockets

Webhooks

Problems

Smart Order Routing WebSocket API

Connection

Endpoints

Authentication

➊ Get OAuth2 Credentials

Sandbox

Production

Response

➋ Establish WebSocket Connection

Connection Lifecycle

Quick Start Example

Operations & Message Formats

Unsubscribe Operation

List Subscriptions Operation

Data Channels

Market Data Channel

Top of Book Channel

Execution Data Channel

Heartbeat Channel

Error Handling

​Connection

​Endpoints

​Authentication

​➊ Get OAuth2 Credentials

​Sandbox

​Production

​Response

​➋ Establish WebSocket Connection

​Connection Lifecycle

​Quick Start Example

​Operations & Message Formats

​Subscribe Operation

​Unsubscribe Operation

​List Subscriptions Operation

​Data Channels

​Market Data Channel

​Top of Book Channel

​Execution Data Channel

​Heartbeat Channel

​Error Handling

Connection

Endpoints

Authentication

➊ Get OAuth2 Credentials

Sandbox

Production

Response

➋ Establish WebSocket Connection

Connection Lifecycle

Quick Start Example

Operations & Message Formats

Subscribe Operation

Unsubscribe Operation

List Subscriptions Operation

Data Channels

Market Data Channel

Top of Book Channel

Execution Data Channel

Heartbeat Channel

Error Handling