> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paxos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WebSocket API Reference

> Event-driven connectivity for payments and trading.

## WebSocket API Options

Paxos offers two WebSocket API solutions:

### Public WebSocket API

Provides secure, real-time market and execution data feeds via public [WebSocket](https://websocket.spec.whatwg.org) connections. No authentication required. Ideal for DMA to itBit and general market data consumption.

### Smart Order Routing WebSocket API

Authenticated, bidirectional WebSocket API for Smart Order Routing platform customers. Requires OAuth2 authentication with the `exchange:read_aggregated_marketdata_stream` scope. [Learn more](/api-reference/websockets/smart-order-routing-overview).

> Smart Order Routing customers should use the [Smart Order Routing WebSocket API](/guides/crypto-brokerage/smart-order-routing-websocket) for enhanced functionality.

## Public WebSocket Feeds

The public WebSocket API provides:

* The [Stablecoin Market Price Feed](#stablecoin-feed) streams event-driven updates for the market index price for external stablecoins.
* The [Market Data Feed](/api-reference/websockets/overview#market-data-feed) streams event-driven updates for the entire order book or for a single market.
* The [Execution Data Feed](/api-reference/websockets/overview#execution-data-feed) streams event information for all markets or for a single market.

> See the Websocket [trading](/guides/crypto-brokerage/websocket) guide for a hands-on introduction.

The WebSocket connections provide a number of advantages when compared to the [v2 API](/api-reference), including real-time event notifications, minimized data transfers over the network and reduced latency when compared to a polling strategy.

## Connection Details

Once a secure (`wss://`) connection is established, each feed begins streaming data, subject to the [rate limits](/guides/developer/rate-limits#websocket-limits).
Both Production and Sandbox data feeds have a built-in, instantaneous failover.
Clients should have a reconnection mechanism in case of server disconnection.

### Sandbox Data Feeds

```shell theme={null}
wss://ws.sandbox.paxos.com/executiondata
wss://ws.sandbox.paxos.com/executiondata/{market}
wss://ws.sandbox.paxos.com/marketdata
wss://ws.sandbox.paxos.com/marketdata/{market}
wss://ws.sandbox.paxos.com/marketdata/stablecoin/{market}
```

### Production Data Feeds

```shell theme={null}
wss://ws.paxos.com/executiondata
wss://ws.paxos.com/executiondata/{market}
wss://ws.paxos.com/marketdata
wss://ws.paxos.com/marketdata/{market}
wss://ws.paxos.com/marketdata/stablecoin/{market}
```

## Execution Data Feed

Upon secure (`wss://`) connection, you will start to receive messages for each market execution (based on the use of the market parameter).
The first message corresponds to the last execution for the market at the point of the connection.
After that, each new message represents a new execution.

If there are no executions for longer periods of time for a particular market upon connection you may not receive any message until a new execution is made.

> Upon reconnection you will receive the last execution for the market, in which case clients should handle duplicate messages. You may use a match number as an idempotent field.

### Execution Data Request

* Sandbox: `wss://ws.sandbox.paxos.com/executiondata`
* Production: `wss://ws.paxos.com/executiondata`

### Execution Data Path Parameter

* Sandbox: `wss://ws.sandbox.paxos.com/executiondata/{market}`
* Production: `wss://ws.paxos.com/executiondata/{market}`

| Parameter | Required | Description                                                                                                                                                      |
| --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `market`  | No       | Filter the data stream for a single market. For example, `BTCUSD` or another market from [available markets](/guides/developer/api-websocket#available-markets). |

### Execution Data Response

| Parameter      | Required | Description                                                                                                                                                                                                          |
| -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `market`       | Yes      | One of the [available markets](/guides/developer/api-websocket#available-markets) or the single market if the `market` [path parameter](/guides/developer/api-websocket#execution-data-path-parameter) is specified. |
| `price`        | Yes      | The execution price.                                                                                                                                                                                                 |
| `amount`       | Yes      | The execution amount.                                                                                                                                                                                                |
| `executed_at`  | Yes      | Timestamp of the execution.                                                                                                                                                                                          |
| `match_number` | Yes      | Unique execution number.                                                                                                                                                                                             |

### Execution Data Example Response

Request URL: `wss://ws.sandbox.paxos.com/executiondata/BTCUSD`

```json theme={null}
{
  "market": "BTCUSD",
  "price": "24228.75",
  "amount": "0.00000412",
  "executed_at": "2023-03-13T18:46:53.386Z",
  "match_number": "6AJVAX7BTCH8"
}
...
```

## Market Data Feed

Once a secure (`wss://`) connection is established, the initial response message shows the state of the order book, including both bids and asks, in the `SNAPSHOT`.
Prices are in descending order for bids and ascending order for asks.

> When streaming data for all markets, differentiate the per-market updates using the `market` field.

### Available Markets

The public feeds may contain inactive markets or markets unavailable for trading.
Availability varies depending on the environment.
For example, we may enable a market in the Sandbox environment for testing but not in Production.
Some Paxos accounts have additional trading restrictions in Production.

> [Get Order Book](/api-reference/endpoints/market-data/get-order-book) retrieves a list of markets available for trading and [List Recent Executions](/api-reference/endpoints/market-data/list-recent-executions) retrieve a list of all platform trades.
> However, these endpoints are not suitable for streaming order book and execution event data.

### Market Data Request

* Sandbox: `wss://ws.sandbox.paxos.com/marketdata`
* Production: `wss://ws.paxos.com/marketdata`

### Market Data Path Parameter

* Sandbox: `wss://ws.sandbox.paxos.com/marketdata/{market}`
* Production: `wss://ws.paxos.com/marketdata/{market}`

| Parameter | Required | Description                                                                                                                                                      |
| --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `market`  | No       | Filter the data stream for a single market. For example, `BTCUSD` or another market from [available markets](/guides/developer/api-websocket#available-markets). |

### Market Data Initial Response

| Parameter        | Required | Description                                                                                                                                                                                                     |
| ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`           | Yes      | The initial value of `SNAPSHOT` shows the state of the order book for both `bids` and `asks`. Subsequent messages show all executed trades, and other order book changes, in the `UPDATE` stream.               |
| `market`         | Yes      | One of the [available markets](/guides/developer/api-websocket#available-markets) or a single market if the `market` [path parameter](/guides/developer/api-websocket#market-data-path-parameter) is specified. |
| `bids`           | Yes      | Includes `bids.price` in descending order and `bids.amount`. Each `price`-`amount` pair represents a level of the book.                                                                                         |
| `asks`           | Yes      | Includes `asks.price` in ascending order and `asks.amount`. Each `price`-`amount` pair represents a level of the book.                                                                                          |
| `final_snapshot` | Yes      | Demarcates the end of the initial `SNAPSHOT`. Initial value always `true`. Subsequent messages in `UPDATE` format.                                                                                              |

### Market Data Update Response

When processing `UPDATE` messages observe the following rules:

* If `side=BUY` and `amount=0`, remove the existing entry with price `price` from the bids list.
* If `side=BUY` and an entry with price `price` already exists in the `bids` list, update the amount for the given entry in the `bids` list to `amount`.
* If `side=BUY` and no entry with price `price` exists in the `bids` list, add an entry with price `price` and amount `amount` to `bids` list.
* If `side=SELL`, apply the logic used as for `BUY` to the `asks` list.

| Parameter | Required | Description                                                                                                                                                                                                       |
| --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`    | Yes      | Value always `UPDATE`. Show all executed trades, and other order book changes, in the data stream.                                                                                                                |
| `market`  | Yes      | One of the [available markets](/guides/developer/api-websocket#available-markets) or the single market if the `market` [path parameter](/guides/developer/api-websocket#market-data-path-parameter) is specified. |
| `side`    | Yes      | Value either `BUY` or `SELL`. Specifies the activity type.                                                                                                                                                        |
| `price`   | Yes      | The current price.                                                                                                                                                                                                |
| `amount`  | Yes      | The current amount.                                                                                                                                                                                               |

### Market Data Example Response

Request URL: `wss://ws.sandbox.paxos.com/marketdata/BTCUSD`

```json theme={null}
{
  "type": "SNAPSHOT",
  "market": "BTCUSD",
  "bids": [
    {
      "price": "19994.25",
      "amount": "0.7755"
    },
    {
      "price": "19993.75",
      "amount": "0.83676985"
    },
    ...
  ],
  "asks": [
    {
      "price": "19994.5",
      "amount": "0.97548541"
    },
    {
      "price": "19996",
      "amount": "1.135"
    },
    ...
  ],
  "final_snapshot": true
}

{
  "type": "UPDATE",
  "market": "BTCUSD",
  "side": "BUY",
  "price": "19958.5",
  "amount": "0.62649999"
}

{
  "type": "UPDATE",
  "market": "BTCUSD",
  "side": "SELL",
  "price": "20115.25",
  "amount": "0"
}
...
```

## Stablecoin Market Price Feed

Once a secure (`wss://`) connection is established, the initial response message shows the market price.
The feed currently supports the USDCUSD market.

### Stablecoin Market Request

* **Sandbox**: `wss://ws.sandbox.paxos.com/marketdata/stablecoin`
* **Production**: `wss://ws.paxos.com/marketdata/stablecoin`

### Stablecoin Market Path Parameter

* **Sandbox**: `wss://ws.sandbox.paxos.com/marketdata/stablecoin/{market}`
* **Production**: `wss://ws.paxos.com/marketdata/stablecoin/{market}`

### Stablecoin Market Response

Price updates are pushed as they occur. The update frequency will typically be around 1 message per second, but may depend on market price volatility.

| Parameter   | Required | Description                                                                                  |
| ----------- | -------- | -------------------------------------------------------------------------------------------- |
| `market`    | Yes      | One of the available markets or the single market if the market path parameter is specified. |
| `price`     | Yes      | The current price to 4 decimals.                                                             |
| `timestamp` | Yes      | The time that the update occurred.                                                           |

### Stablecoin Market Example Response

Request URL: `wss://ws.sandbox.paxos.com/marketdata/stablecoin/USDCUSD`

```json theme={null}
{"market":"USDCUSD","price":"1.0001","timestamp":"2024-11-04T18:11:09.042391267Z"}

{"market":"USDCUSD","price":"1.0001","timestamp":"2024-11-04T18:11:10.049787567Z"}

{"market":"USDCUSD","price":"1.0001","timestamp":"2024-11-04T18:11:11.042710464Z"}

...
```