跳到主要内容

合约 WebSocket API

合约 WebSocket API 允许您订阅实时的公共市场数据和私有用户数据更新。

合约 API 对公共频道使用 基于 URL 的订阅 (URL-based subscriptions)，对私有数据使用单一的 验证流 (Authenticated Stream)。

错误处理与状态码 (Error Handling & Status Codes)​

由于订阅基于 URL，错误主要发生在 连接握手 (connection handshake) 阶段：

  • HTTP 101 Switching Protocols: 连接成功。
  • HTTP 401 Unauthorized: (私有流) Authorization header 无效或缺失。
  • HTTP 400 Bad Request: URL 参数无效。
  • HTTP 500 Internal Server Error: 连接期间服务器端错误。

如果在握手后连接中断或无效，服务器将直接 关闭连接。

公共频道 (Public Channels)​

公共频道通过连接到特定的 WebSocket URL 访问。无需身份验证。

市场深度 (Order Book)​

首先推送快照，随后持续推送实时变更。

URL​

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

请求示例​

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

响应示例 (快照)​

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

市场成交 (Market Trades)​

订阅实时成交历史。

URL​

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

请求示例​

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

响应示例​

[
    {
        "id": "5aefeab9-6840-0000-0001-0000056fe3c8",
        "symbol": "BTCUSD",
        "price": 11178.5,
        "size": 100,
        "matchedAt": 1562288776609,
        "side": "BUY"
    }
]

K 线 (Candlestick)​

订阅 OHLCV 数据。

URL​

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

支持的周期: 1MIN, 5MIN, 15MIN, 30MIN, 1H, 4H, 6H, 12H, 1D

请求示例​

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

响应示例​

[
    {
        "symbol": "BTCUSD",
        "type": "1MIN",
        "time": 1562301000000,
        "open": 11119.5,
        "close": 11109.5,
        "high": 11123.5,
        "low": 11109.5,
        "volume": 3427
    }
]

合约信息 (Contract Instruments)​

获取实时合约详情 (资金费率、未平仓合约等)。

单个交易对 (Single Symbol)​

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

所有交易对 (All Instruments)​

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

响应示例​

[
    {
        "symbol": "BTCUSD",
        "fundingRate": 0,
        "markPrice": 11255.51,
        "indexPrice": 11255.51,
        "turnover24h": 0.354295837,
        "openInterest": 3412,
        "last24hMaxPrice": 11290,
        "last24hMinPrice": 11290
    }
]

私有流 (Private Stream - Authenticated)​

私有数据 (资产、持仓、订单、成交) 全部通过单一的 Stream 频道推送。

身份验证​

身份验证在 WebSocket 握手期间通过 HTTP Authorization Header 处理。

Header 格式: Authorization: Bearer {YOUR_JWT_TOKEN}

URL​

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

请求示例​

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

响应数据结构​

流推送包含以下键更新的 JSON 对象：

  • cash (账户余额)
  • positions (持仓)
  • orders (订单)
  • trades (用户成交)

响应示例​

{
    "cash": {
        "currency": "USDT",
        "balances": 0.2,
        "available": 0.2,
        "margin": 0,
        "orderMargin": 0,
        "positionMargin": 0
    },
    "positions": [
        {
            "symbol": "BTCUSDT",
            "leverage": 100,
            "marginRate": 0.01,
            "unrealizedPnl": 0,
            "liquidatePrice": 0
        }
    ],
    "orders": [
        {
             "id": 888888,
             "symbol": "BTCUSD",
             "side": "BUY",
             "type": "LIMIT",
             "price": 49500.0,
             "size": 1.0,
             "filled": 0.5,
             "status": "PARTIALLY_FILLED",
             "ts": 1625451034000
        }
    ],
    "trades": [
        {
             "id": 999999,
             "orderId": 888888,
             "symbol": "BTCUSD",
             "price": 49500.0,
             "size": 0.5,
             "fee": 0.05,
             "side": "BUY",
             "role": "MAKER"
        }
    ]
}