WebSocket API

WebSocket API for real-time trading operations and execution reports.

Connection Endpoint

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

Mainnet: N/A

---

Message Format

All messages use JSON with a type field discriminator.

Request:

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

Response:

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

Request:

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

Success Response:

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

For signature construction, see Signatures - 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.

See Nonce & Rate Limits for details.

---

Error Responses

All errors use the same format:

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

For complete error code reference, see Error Codes.

---

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 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 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 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 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 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.