> For the complete documentation index, see [llms.txt](https://docs.hello.trade/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hello.trade/developer-tools/websocket-api.md).

# WebSocket API

## Connection Endpoint

**Testnet**: `wss://api.app.hello.trade/ws`

**Mainnet**: N/A

***

## Message Format

All messages use JSON with a `type` field discriminator.

**Request:**

```json
{
  "type": "authenticate",
  ...
}
```

**Response:**

```json
{
  "type": "authenticateSuccess",
  ...
}
```

***

## Connection Flow

1. **Connect** to WebSocket endpoint
2. **Authenticate** with EIP-191 signature
3. **Subscribe** to trading stream (optional, required for execution reports)
4. **Trade** (place, cancel, replace orders)
5. **Logout** or disconnect when done

***

## Authentication

Connections must authenticate before performing trading operations. See [Authentication & Account Model](/developer-tools/authentication-and-account-model.md) for details.

**Request:**

```json
{
  "type": "authenticate",
  "signature": {
    "sig": "0x...",
    "payload": "0x02..."
  }
}
```

**Success Response:**

```json
{
  "type": "authenticateSuccess",
  "account": "0x742d35Cc6634C0532925a3b844Bc9e7595f12345",
  "message": "Authentication successful"
}
```

For signature construction, see [Signatures - EIP-191 Operations](/developer-tools/signatures.md#eip-191-operations).

***

## Connection Limits

| Limit                       | Value      |
| --------------------------- | ---------- |
| Max connections per account | 8          |
| Idle timeout                | 30 seconds |
| Ping interval               | 15 seconds |

Connections exceeding idle timeout are automatically disconnected. Maintain connection by:

* Responding to ping frames
* Sending requests

***

## Rate Limiting

Maximum request rate: **20 requests/second per wallet** (rolling 1-second window, orders included). Applies to wallet-authenticated requests; unauthenticated reads are limited per client IP — see [Nonce & Rate Limits](/developer-tools/nonce-and-rate-limits.md).

See [Nonce & Rate Limits](/developer-tools/nonce-and-rate-limits.md) for details.

***

## Error Responses

All errors use the same format:

```json
{
  "type": "error",
  "code": 4001,
  "message": "Signature verification failed"
}
```

For complete error code reference, see [Error Codes](/developer-tools/error-codes.md).

***

## Message Types

### Connection Management

| Message Type       | Description                         | Authentication Required |
| ------------------ | ----------------------------------- | ----------------------- |
| `authenticate`     | Authenticate connection with wallet | No                      |
| `logout`           | Clear authentication state          | Yes                     |
| `subscribeTrading` | Subscribe to execution reports      | Yes                     |

See [Connection Management](/developer-tools/websocket-api/connection-management.md) for details.

### Trading Operations

| Message Type     | Description                                           | Authentication Required |
| ---------------- | ----------------------------------------------------- | ----------------------- |
| `placeOrder`     | Place new order                                       | Yes                     |
| `replaceOrder`   | Atomically replace existing order                     | Yes                     |
| `cancelOrder`    | Cancel order by ID                                    | Yes                     |
| `cancelAll`      | Cancel all orders (optionally by instrument)          | Yes                     |
| `transferMargin` | Transfer collateral between cross and isolated margin | Yes                     |

See [Trading Operations](/developer-tools/websocket-api/trading-operations.md) for details.

### Execution Reports

After subscribing to the trading stream, execution reports are automatically pushed for:

* Order status changes (new, filled, cancelled, etc.)
* Trade executions
* Account events (deposits, withdrawals, margin transfers, leverage updates, liquidations)

See [Execution Reports](/developer-tools/websocket-api/execution-reports.md) for details.

### Liquidation Auction

| Message Type               | Direction        | Description                                                                         | Authentication Required |
| -------------------------- | ---------------- | ----------------------------------------------------------------------------------- | ----------------------- |
| `manualLiquidationOffer`   | Gateway → Client | Broadcast of a position open for claim during liquidation                           | Yes (subscribed)        |
| `claimLiquidation`         | Client → Gateway | Claim an open offer with a signed order                                             | Yes                     |
| `claimLiquidationAccepted` | Gateway → Client | Ack that a claim entered the auction                                                | Yes                     |
| `claimLiquidationResult`   | Gateway → Client | Terminal win/lose outcome sent to each accepted claimant after the auction resolves | Yes                     |

See [Liquidation Auction](/developer-tools/websocket-api/liquidation-auction.md) for details.

### Account Summary Stream

| Message Type                | Direction        | Description                                                                                                                                            | Authentication Required |
| --------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- |
| `subscribeAccountSummary`   | Client → Gateway | Subscribe to account summary updates (margin, positions, withdrawable)                                                                                 | Yes                     |
| `unsubscribeAccountSummary` | Client → Gateway | Stop receiving account summary updates                                                                                                                 | Yes                     |
| `accountSummary`            | Gateway → Client | Snapshot (on subscribe), then a full snapshot on each position/margin/balance change (fills, busts, liquidations, funding, leverage, deposit/withdraw) | Yes (subscribed)        |

Independent of `subscribeTrading`. See [Account Summary Stream](/developer-tools/websocket-api/account-summary.md) for details.

***

## WebSocket vs REST

| Operation                   | WebSocket  | REST         |
| --------------------------- | ---------- | ------------ |
| Place/Cancel/Replace Orders | ✓          | -            |
| Real-time Execution Reports | ✓          | -            |
| Deposit/Withdraw Margin     | -          | ✓            |
| Update Leverage             | -          | ✓            |
| Account Summary             | ✓ (stream) | ✓ (snapshot) |
| Historical Orders/Trades    | -          | ✓            |

For REST API operations, see [REST API](/developer-tools/rest-api.md).