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

# WebSocket API

> JSON-RPC 2.0 trading and subscription protocol for the Joyride gateway.

## Status

Use the `WebSocket Reference` tab for generated channel and message reference.

This page remains the protocol guide and highlights the runtime behavior that matters most when integrating.

## Transport

* Protocol: raw WebSocket
* Endpoint: `wss://joyride.exchange/api/v1`
* Message envelope: JSON-RPC 2.0
* Trading: WebSocket only
* Market-data subscriptions: WebSocket only

### Request shape

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "private/buy",
  "params": {}
}
```

### Success response

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}
```

### Subscription notification

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "subscription",
  "params": {
    "channel": "book.SOL_USDC-28FEB26-150-C.10",
    "data": {}
  }
}
```

## Core methods

### Authentication

* `public/get_nonce`
* `public/auth`

### Trading

* `private/buy`
* `private/sell`
* `private/cancel`
* `private/cancel_all`

### Queries

* `public/get_instruments`
* `public/get_market_config`
* `private/get_open_orders`
* `private/get_account`

### Subscriptions

* `public/subscribe`
* `public/unsubscribe`

## Channel patterns

| Channel                        | Auth | Description                                                  |
| ------------------------------ | ---- | ------------------------------------------------------------ |
| `book.{instrument_id}.{depth}` | no   | Book snapshots and updates                                   |
| `trades.{instrument_id}`       | no   | Public trade feed                                            |
| `tickers.{instrument_id}`      | no   | Best bid/ask, spread, mid, and spot price for one instrument |
| `spot.{asset}`                 | no   | Real-time spot price updates for one asset                   |
| `candle.{asset}.{timeframe}`   | no   | Live candle relay from price-history                         |
| `user.orders`                  | yes  | Order status updates for the authenticated user              |
| `user.trades`                  | yes  | Trade notifications for the authenticated user               |
| `social`                       | yes  | Social feed snapshot and live activity events                |
| `leaderboard`                  | yes  | Live leaderboard snapshots                                   |
| `settlement`                   | yes  | Settlement timing updates and per-user settlement results    |
| `logs`                         | no   | Gateway log stream for dashboards and debugging              |

## Authenticated push events

Some server notifications are sent to authenticated sessions without an explicit `public/subscribe`:

* `instruments` when a new round is bootstrapped
* `settlement_complete` when a settlement round finishes

## Common application errors

| Code   | Meaning                             |
| ------ | ----------------------------------- |
| `1001` | Not authenticated                   |
| `1002` | Insufficient balance                |
| `1003` | Order not found                     |
| `1004` | Instrument not found                |
| `1005` | Invalid price                       |
| `1006` | Invalid size                        |
| `1007` | Rate limit exceeded                 |
| `1008` | Order already cancelled or filled   |
| `1009` | Market closed or instrument expired |
| `1010` | Authentication failed               |

## Reference split

* `WebSocket Reference` tab: generated reference from `asyncapi.yaml`
* This page: conceptual guide and notable protocol behavior