> 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/connection-management.md).

# Connection Management

## Connection Basics

HelloTrade uses WebSocket endpoints for real-time data exchange and trading.

**Endpoints:**

| Service     | Environment | Endpoint                              |
| ----------- | ----------- | ------------------------------------- |
| Trading     | Production  | `wss://api.app.hello.trade/ws`        |
| Market Data | Production  | `wss://marketdata.app.hello.trade/ws` |

Once connected to the trading endpoint, you must authenticate your connection before performing trading operations or subscribing to execution reports.

**CLI Example:**

```bash
wscat -c wss://api.app.hello.trade/ws
# After connection, send authentication (with encoded payload):
{"type":"authenticate","signature":{"sig":"0x...","payload":"0x02..."}}
# Then subscribe to trading:
{"type":"subscribeTrading"}
```

### Heartbeat

The server sends periodic ping frames. Clients must respond with pong frames to maintain the connection.

| Setting       | Value      |
| ------------- | ---------- |
| Ping interval | 15 seconds |
| Idle Timeout  | 30 seconds |

Connections are closed after 30 seconds of inactivity (no messages or ping/pong responses).

### Reconnection

On disconnect:

1. Reconnect to WebSocket endpoint
2. Re-authenticate with fresh nonce
3. Re-subscribe to trading stream
4. Reconcile order state from initial snapshot

Always reconcile your local order state with the snapshot received after re-subscribing.

***

## authenticate

Authenticate WebSocket connection with EIP-191 signature.

### Request

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

| Field               | Type   | Description                                                |
| ------------------- | ------ | ---------------------------------------------------------- |
| `signature.sig`     | string | EIP-191 signature (hex-encoded with 0x prefix)             |
| `signature.payload` | string | Encoded SimpleSignaturePayload (type discriminator `0x02`) |

**Signature Construction:**

1. Create SimpleSignaturePayload struct with `account`, `nonce`, and `deadline`
2. Sign the message string: `{account}:{nonce}` (note: deadline not in message, only in struct)
3. Encode the struct with type discriminator byte `0x02`

See [Signatures - EIP-191 Operations](/developer-tools/signatures.md#eip-191-operations) for complete details.

### Success Response

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

### Common Errors

| Code | Cause                                             |
| ---- | ------------------------------------------------- |
| 4001 | Signature verification failed                     |
| 4002 | Invalid nonce (expired, replay, or out of window) |
| 4029 | Rate limit exceeded                               |
| 5000 | Connection limit exceeded (>8 connections)        |
| 5003 | Failed to create or retrieve account              |

***

## logout

Clear authentication state and unsubscribe from trading stream.

**Authentication Required:** Yes

### Request

```json
{
  "type": "logout"
}
```

No parameters required.

### Success Response

```json
{
  "type": "logoutSuccess",
  "message": "Logout successful"
}
```

Connection returns to unauthenticated state. To trade again, send new `authenticate` message.

***

## subscribeTrading

Subscribe to execution reports stream.

**Authentication Required:** Yes

After successful subscription, the gateway automatically:

1. Sends initial order snapshot (all resting orders for the account)
2. Streams real-time execution reports for order updates, trades, and account events

### Request

```json
{
  "type": "subscribeTrading"
}
```

No parameters required. Uses authenticated wallet from `authenticate` message.

### Success Response

```json
{
  "type": "subscribeTradingSuccess",
  "account": "0x742d35Cc6634C0532925a3b844Bc9e7595f12345",
  "message": "Subscribed to trading stream. Received 3 orders in snapshot. Execution reports will follow."
}
```

### Execution Report Flow

After subscription:

1. **Order snapshot** - All resting orders sent as execution reports with `messageType: "OrderStatus"`
2. **Real-time updates** - Ongoing execution reports for:
   * Order status changes (filled, cancelled, etc.)
   * Trade executions
   * Account events (deposits, withdrawals, leverage updates, liquidations)

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

### Common Errors

| Code  | Cause                                         |
| ----- | --------------------------------------------- |
| 4003  | Not authenticated (send `authenticate` first) |
| 4029  | Rate limit exceeded                           |
| 4033  | Already subscribed to trading stream          |
| 5000  | Internal error                                |
| 5001+ | Exchange error (5001 + exchange error code)   |

***