Spot WebSocket API

Connection Details

• Endpoint: wss://api.big.one/ws/v2
• Protocols: json (default) or proto (Google Protocol Buffers).

Protocol Selection

We support two protocols for data transmission:

1. JSON: Human-readable, easy to debug. Default behavior.
2. Proto (Protobuf): Binary format, smaller payload, lower latency. Recommended for high-frequency trading.
   • To use Proto, set the HTTP Header Sec-WebSocket-Protocol: proto during the handshake.
   • View Proto Definitions

KeepAlive (Heartbeat)

To prevent the connection from being closed by intermediate network nodes (like load balancers), clients should send a Ping frame or a custom Heartbeat message regularly.

Authentication

Authentication is required for Private Channels (e.g., User Orders, User Accounts).

How to Authenticate

Send an authenticateCustomerRequest immediately after connecting.

Request

{
  "requestId": "1",
  "authenticateCustomerRequest": {
    "token": "Bearer {YOUR_JWT_TOKEN}"
  }
}

You can generate the JWT Token using your API Key and Secret. See Authentication Guide for details.

Parameters

Field	Type	Description	Required
token	string	Bearer {YOUR_JWT_TOKEN}	No (if defined in object)

Request & Response Format

All WebSocket messages follow a standard JSON structure (unless using Proto).

Request Structure

Every request must include a requestId to track the response.

{
  "requestId": "unique_id_123",
  "subscribeRequestName": { ...params }
}

Response Structure

Responses include the requestId from the original request.

Success

Subscribing usually results in an immediate Snapshot followed by Updates.

Error

{
  "requestId": "1",
  "error": {
    "code": 45000,
    "message": "Error description"
  }
}

Error Codes

Code	Type	Description
45000	System Error	Internal gRPC or system error.
45001	Auth Error	Login status invalid or token expired.
Other	General	Default error.

Public Channels

Market Depth (Order Book)

Subscribe to real-time order book changes.

Subscribe

{
  "requestId": "1",
  "subscribeMarketDepthRequest": {
    "market": "BTC-USDT"
  }
}

Parameters

Field	Type	Description	Required
market	string	Market symbol (e.g., BTC-USDT)	Yes

Unsubscribe

{
  "requestId": "1",
  "unsubscribeMarketDepthRequest": {
    "market": "BTC-USDT"
  }
}

Data Format

• Snapshot: Full order book (bids and asks).
• Update: Incremental changes.

Note: changeId and prevId are sequential. changeId of the current message should equal prevId of the next message. Use this to detect missing packets.

Market Depth Models

Depth (Snapshot/Update)

Field	Type	Description
market	string	Market symbol (e.g., BTC-USDT)
bids	[PriceLevel]	List of bid orders (Buy side)
asks	[PriceLevel]	List of ask orders (Sell side)
changeId	string	Sequence ID of this update
prevId	string	Sequence ID of the previous update

PriceLevel

Field	Type	Description
price	string	Price level
amount	string	Total quantity at this price
orderCount	integer	Number of individual orders at this price

Market Candles (K-Line)

Subscribe to OHLCV (Open, High, Low, Close, Volume) data updates.

Subscribe

{
  "requestId": "2",
  "subscribeMarketCandlesRequest": {
    "market": "BTC-USDT",
    "period": "MIN5",
    "limit": "20"
  }
}

Parameters

Field	Type	Description	Required
market	string	Market symbol	Yes
period	string	Time period (e.g., MIN5)	Yes
limit	integer	Number of candles (default 20)	No

Supported Periods: MIN1, MIN5, MIN15, MIN30, HOUR1, HOUR3, HOUR4, HOUR6, HOUR12, DAY1, WEEK1.

Unsubscribe

{
  "requestId": "2",
  "unsubscribeMarketCandlesRequest": {
    "market": "BTC-USDT",
    "period": "MIN5"
  }
}

Candle Model

Field	Type	Description
market	string	Market symbol
time	string	Candle open time (UTC ISO8601)
open	string	Opening price
high	string	Highest price
low	string	Lowest price
close	string	Closing price
volume	string	Volume during this period
period	string	Time period identifier (e.g., MIN5)

Market Ticker

Subscribe to 24-hour rolling ticker data.

Subscribe

{
  "requestId": "3",
  "subscribeMarketsTickerRequest": {
    "markets": ["BTC-USDT", "ETH-USDT"]
  }
}

Parameters

Field	Type	Description	Required
markets	array	List of market symbols (e.g., ["BTC-USDT"])	Yes

Unsubscribe

{
  "requestId": "3",
  "unsubscribeMarketsTickerRequest": {
    "markets": ["BTC-USDT", "ETH-USDT"]
  }
}

Ticker Model

Field	Type	Description
market	string	Market symbol
open	string	Price 24 hours ago
high	string	Highest price in last 24h
low	string	Lowest price in last 24h
close	string	Last traded price
volume	string	Trading volume in last 24h
bid	PriceLevel	Best bid price and quantity
ask	PriceLevel	Best ask price and quantity

Market Trades

Subscribe to real-time trade execution history.

Subscribe

{
  "requestId": "4",
  "subscribeMarketTradesRequest": {
    "market": "BTC-USDT",
    "limit": 20
  }
}

Parameters

Field	Type	Description	Required
market	string	Market symbol	Yes
limit	integer	Number of trades (default 20)	No

Unsubscribe

{
  "requestId": "4",
  "unsubscribeMarketTradesRequest": {
    "market": "BTC-USDT"
  }
}

Trade Model

Field	Type	Description
id	string	Unique trade ID
market	string	Market symbol
price	string	Execution price
amount	string	Execution amount
takerSide	string	Side of the taker (ASK or BID)
createdAt	string	Execution time (UTC ISO8601)

Note: In public trade streams, makerOrder and takerOrder fields are always null.

Private Channels (Auth Required)

User Account

Subscribe to balance changes for your account.

Subscribe

{
  "requestId": "5",
  "subscribeViewerAccountsRequest": {}
}

Unsubscribe

{
  "requestId": "5",
  "unsubscribeViewerAccountsRequest": {}
}

Account Model

Field	Type	Description
asset	string	Asset symbol (e.g., BTC)
balance	string	Available balance
lockedBalance	string	Frozen/Locked balance (in orders)

User Orders

Subscribe to order status updates (e.g., FILLED, CANCELLED).

Subscribe (Specific Market)

{
  "requestId": "6",
  "subscribeViewerOrdersRequest": {
    "market": "BTC-USDT"
  }
}

Parameters

Field	Type	Description	Required
market	string	Market symbol	Yes

Unsubscribe

{
  "requestId": "6",
  "unsubscribeViewerOrdersRequest": {
    "market": "BTC-USDT"
  }
}

Subscribe (All Markets)

{
  "requestId": "7",
  "subscribeAllViewerOrdersRequest": {}
}

Note: subscribeAllViewerOrdersRequest only pushes updates (no initial snapshot).

Unsubscribe

{
  "requestId": "7",
  "unsubscribeAllViewerOrdersRequest": {}
}

Order Model

Field	Type	Description
id	string	Unique order ID
market	string	Market symbol
price	string	Order price
amount	string	Order original amount
filledAmount	string	Amount filled so far
avgDealPrice	string	Average execution price
side	string	ASK or BID
state	string	PENDING, FILLED, CANCELLED
createdAt	string	Order creation time
updatedAt	string	Last update time