Contract WebSocket API

The Contract WebSocket API allows you to subscribe to real-time public market data and private user data updates.

The Contract API uses URL-based subscriptions for public channels and a single Authenticated Stream for private data.

Error Handling & Status Codes

Since subscriptions are URL-based, errors primarily occur during the connection handshake:

• HTTP 101 Switching Protocols: Connection successful.
• HTTP 401 Unauthorized: (Private Stream) Invalid or missing Authorization header.
• HTTP 400 Bad Request: Invalid parameters in the URL.
• HTTP 500 Internal Server Error: Server-side issue during connection.

If a connection is dropping or invalid after the handshake, the server will simply close the connection.

---

Public Channels

Public channels are accessed by connecting to specific WebSocket URLs. No authentication is required.

Market Depth (Order Book)

Push snapshot at first, and keep pushing real-time changes later.

URL

wss://api.big.one/ws/contract/v2/depth@{symbol}

Request Example

wscat -c wss://api.big.one/ws/contract/v2/depth@BTCUSD

Response Example (Snapshot)

{
    "to": 91277134,
    "bestPrices": {
        "ask": 11202.5,
        "bid": 11192.5
    },
    "lastPrice": 11183.5,
    "bids": {
        "11192": 35,
        "11184": 742,
        "11192.5": 389,
        "11188": 293
    },
    "asks": {
        "11202.5": 1806,
        "11212.5": 2138,
        "11211.5": 19308
    },
    "from": 0
}

Response Example (Real-time)

{
    "bids": {
        "11183": 3500
    },
    "lastPrice": 11183.5,
    "from": 91277135,
    "bestPrices": {
        "ask": 11202.5,
        "bid": 11192.5
    },
    "asks": {},
    "to": 91277135
}

Market Trades

Subscribe to real-time trade execution history.

URL

wss://api.big.one/ws/contract/v2/trades@{symbol}

Request Example

wscat -c wss://api.big.one/ws/contract/v2/trades@BTCUSD

Response Example (Snapshot)

[
    {
        "id": "5aefeab9-6840-0000-0001-0000056fe3c8",
        "symbol": "BTCUSD",
        "price": 11178.5,
        "size": 100,
        "matchedAt": 1562288776609,
        "side": "BUY"
    },
    {
        "id": "5aefeb33-e940-0000-0001-0000056fea51",
        "symbol": "BTCUSD",
        "price": 11180,
        "size": 60,
        "matchedAt": 1562288902053,
        "side": "SELL"
    }
]

Response Example (Real-time)

[
    {
        "id": "5af01b50-9700-0000-0001-000005727d9b",
        "symbol": "BTCUSD",
        "price": 11138,
        "size": 267,
        "matchedAt": 1562301514332,
        "side": "BUY"
    }
]

Candlestick (K-Line)

Subscribe to OHLCV data.

URL

wss://api.big.one/ws/contract/v2/candlesticks/{period}@{symbol}

Supported Periods: 1MIN, 5MIN, 15MIN, 30MIN, 1H, 4H, 6H, 12H, 1D

Request Example

wscat -c wss://api.big.one/ws/contract/v2/candlesticks/1MIN@BTCUSD

Response Example

[
    {
        "symbol": "BTCUSD",
        "type": "1MIN",
        "time": 1562301000000,
        "open": 11119.5,
        "close": 11109.5,
        "high": 11123.5,
        "low": 11109.5,
        "nTrades": 4,
        "volume": 3427,
        "turnover": 0.30820388075,
        "version": 91383701,
        "nextTs": 1562301060000
    }
]

Contract Instruments

Get real-time contract details (funding rate, open interest, etc.).

URL

• Single Symbol: wss://api.big.one/ws/contract/v2/instruments@{symbol}
• All Instruments: wss://api.big.one/ws/contract/v2/instruments

Parameters

Parameter	Type	Required	Description
symbol	string	No	Contract Symbol (e.g., BTCUSD). If omitted, subscribes to all instruments.

Request Example (Single Symbol)

wscat -c wss://api.big.one/ws/contract/v2/instruments@BTCUSD

Request Example (All Instruments)

wscat -c wss://api.big.one/ws/contract/v2/instruments

Response Example

[
    {
        "turnover24h": 0.354295837,
        "openInterest": 3412,
        "volume24hInUsd": 4000,
        "fundingRate": 0,
        "volume24h": 4000,
        "last24hMaxPrice": 11290,
        "btcPrice": 11255.51,
        "latestPrice": 11290,
        "symbol": "BTCUSD",
        "openValue": 0.300825969916003,
        "last24hMinPrice": 11290,
        "openTime": 0,
        "markPrice": 11255.51,
        "indexPrice": 11255.51
    }
]

---

Private Stream (Authenticated)

Private data (Cash, Positions, Orders, Trades) is all pushed through a single Stream channel.

Authentication

Authentication is handled via the HTTP Authorization Header during the WebSocket handshake.

Header Format: Authorization: Bearer {YOUR_JWT_TOKEN}

URL

wss://api.big.one/ws/contract/v2/stream

Request Example

wscat -H "Authorization: Bearer YOUR_JWT_TOKEN" -c wss://api.big.one/ws/contract/v2/stream

Response Data Structure

The stream pushes a JSON object containing any updates to the following keys:

• cash (Account Balance)
• positions
• orders (Order Status Updates)
• trades (User Trades)

Response Example

{
    "cash": {
        "id": "5aed7b45-5d19-40f2-0005-ca49d01f33e3",
        "userId": "5aec525e-335d-4724-0005-20153b361f89",
        "currency": "USDT",
        "balances": 0.2,
        "available": 0.2,
        "margin": 0,
        "positionMargin": 0,
        "orderMargin": 0,
        "positionValue": 0,
        "unrealizedPnl": 0,
        "marginBalances": 0.2,
        "marginRate": 0,
        "leverage": 0
    },
    "positions": [
        {
            "id": "5aed7b45-5d19-40f2-0005-ca49d01f33e3",
            "userId": "5aec525e-335d-4724-0005-20153b361f89",
            "symbol": "BTCUSD",
            "currency": "BTC",
            "isCross": true,
            "marginRate": 0.01,
            "feeRateTaker": 0.0007,
            "feeRateMaker": 0.0006,
            "size": 100,
            "notional": 0.008857,
            "initMargin": 0.00008857,
            "margin": 0.01,
            "orderMargin": 0,
            "realisedPnl": 0,
            "totalPnl": 0,
            "markPrice": 11303.14,
            "riskLimit": 100,
            "liquidatePrice": 10000.5,
            "entryPrice": 11290,
            "unrealizedPnl": 0,
            "leverage": 100,
            "equity": 0.1,
            "value": 1.2,
            "risk": 0,
            "rom": 0,
            "buyingNotional": 0,
            "sellingNotional": -0.116909,
            "buyingSize": 0,
            "sellingSize": -1400,
            "seqNo": 0
        }
    ],
    "orders": [
        {
             "id": "5aefeab9-6840-0000-0001-0000056fe3c8",
             "userId": "5aec525e-335d-4724-0005-20153b361f89",
             "liquidateUserId": null,
             "symbol": "BTCUSD",
             "currency": "USDT",
             "type": "LIMIT",
             "side": "BUY",
             "status": "PARTIALLY_FILLED",
             "price": 49500.0,
             "avgPrice": 49450,
             "size": 1.0,
             "notional": 49500,
             "filled": 0.5,
             "filledNotional": 24725
        }
    ],
    "trades": [
        {
             "id": "5aefeab9-6840-0000-0001-0000056fe3c8",
             "orderId": "5aefeab9-6840-0000-0001-0000056fe3c8",
             "symbol": "BTCUSD",
             "side": "BUY",
             "price": 49500.0,
             "size": 0.5,
             "notional": 24750,
             "fee": 0.05,
             "feeRate": 0.002,
             "pnl": 0
        }
    ]
}