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

# WebSocket API

> Stream live market data and your own order activity over a single socket.

The SOAR WebSocket API pushes live data as it happens, so you do not have to poll
the REST API for prices, order books, or the status of your own orders.

```
wss://ws.trysoar.com
```

Staging is at `wss://ws.staging.trysoar.com`.

Every frame in both directions is a JSON object with a `type` field.

## Two kinds of data

The socket carries two classes of traffic, and they have different access rules.

<CardGroup cols={2}>
  <Card title="Market data" icon="tower-broadcast" href="/websockets/subscriptions">
    Trades, order books, tickers and implied values. Public — **no credential
    required**. Connect and subscribe.
  </Card>

  <Card title="Your private stream" icon="wallet" href="/websockets/connection">
    Your fills, orders and positions. Requires an API key with the `read`
    scope.
  </Card>
</CardGroup>

Market data carries no per-user information, which is why it needs no
credential. The private stream is scoped to the account that owns the API key
you authenticate with.

## Getting started

<Steps>
  <Step title="Connect">
    Open a socket to `wss://ws.trysoar.com`. No headers or handshake
    parameters are required.
  </Step>

  <Step title="Subscribe to market data">
    Send a [`subscribe`](/websockets/subscriptions) frame naming the markets
    you care about.

    ```json theme={null}
    {"type":"subscribe","data":{"targets":[{"target":"event-market","data":{"ticker":"ANTHROPIC-VALUATION-26Q3-2.1T"}}]}}
    ```
  </Step>

  <Step title="Authenticate, if you want your own activity">
    Send an [`authenticate`](/websockets/connection) frame carrying an API key
    with the `read` scope.

    ```json theme={null}
    {"type":"authenticate","data":{"token":"soar_sk_..."}}
    ```
  </Step>

  <Step title="Keep the socket alive">
    Send a [`ping`](/websockets/keep-alive) at least every 5 minutes.

    ```json theme={null}
    {"type":"ping","data":{}}
    ```
  </Step>
</Steps>

## Message types

Server frames arrive under one of these envelopes. The specific payload lives in
`data`, discriminated by `data.type`.

| `type` | Carries | Access |
| - | - | - |
| `market-update` | [Trades](/websockets/public-trades), [order books](/websockets/orderbook-updates), [tickers](/websockets/market-ticker), [implied values](/websockets/implied-value) | Public |
| `prediction-market-update` | Your [fills](/websockets/user-fills), [orders](/websockets/user-orders), [positions](/websockets/market-positions) | API key, `read` |
| `success` | Acknowledgement of an `authenticate` frame | — |
| `error` | A [failure code](/websockets/errors-and-limits) and message | — |

Client frames are `subscribe`, `authenticate` and `ping`. There is no
`unsubscribe` frame — `subscribe` replaces your entire subscription set, so
sending a smaller set is how you unsubscribe.

## Conventions

* **Prices** are integer cents from 1 to 99. A price of `62` means 62¢, or an
  implied 62% probability.
* **Sizes** are whole shares.
* **`ts`** is a Unix timestamp in **nanoseconds**, not milliseconds. Divide by
  1,000,000 before handing it to a millisecond-based date constructor.
* **`orderId`** is always a string. See [User Fills](/websockets/user-fills).

## Versioning

This is the frozen **v1** contract. The message types documented under Market
Data and Private Stream will not change shape without a new version.

There is no version handshake — omitting a version means v1. A
`data.protocolVersion` field on `authenticate` is reserved for a future
revision.

The machine-readable contract is served as markdown at
[`ws.trysoar.com/v1/contract`](https://ws.trysoar.com/v1/contract). The REST
API is described by [`api.trysoar.com/v1/openapi.yaml`](https://api.trysoar.com/v1/openapi.yaml).

<Note>
  Some frames you may observe on the wire — `project-viewer-update`,
  `notification`, and `market-update` frames whose `data.type` is `post` or
  `stats` — are first-party application traffic. They may change or disappear
  without notice. Do not build on them.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.