Connection Management

WebSocket connection lifecycle management (authenticate, logout, subscribe)

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:

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

{
  "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 for complete details.

Success Response

{
  "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

{
  "type": "logout"
}

No parameters required.

Success Response

{
  "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

{
  "type": "subscribeTrading"
}

No parameters required. Uses authenticated wallet from authenticate message.

Success Response

{
  "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 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)

---