Hyperliquid API

BBX Open API provides real-time interfaces for the Hyperliquid exchange, covering tickers, fills, orders, account analytics, address discovery, risk metrics, and the unified Info API.

WS/api/upgrade/v2/hl/ws

WebSocket: Official Subscription-Compatible Endpoint

Path: /api/upgrade/v2/hl/ws

This endpoint is compatible with the Hyperliquid official WebSocket API subscription format ({"method":"subscribe","subscription":{...}}).

Supported Subscription Types (`subscription.type`)

trades
openOrders
clearinghouseState
l2Book
bbo
candle
userFills
userNonFundingLedgerUpdates

`candle` Subscription

Subscription message:

{
  "method": "subscribe",
  "subscription": {
    "type": "candle",
    "coin": "BTC",
    "interval": "1m"
  }
}

Supported interval values: 1s, 5s, 15s, 1m, 15m, 1h, 4h
Minimum push interval: 0.5s
Additional fields:
- a: volume (quote unit)
- nb / vb / ab: the buy_taker portion of n / v / a

Subscription Example

trades

{
  "method": "subscribe",
  "subscription": {
    "type": "trades",
    "coin": "BTC"
  }
}

WS/api/upgrade/v2/hl/ws/fills

WebSocket: Subscribe to User Fills

Subscribes to user fills (fills) and supports multiple addresses.

Subscribe and Unsubscribe

Subscribe: client sends {"type":"subscribe", ...} and the server replies {"type":"subscribe"}
Unsubscribe: client sends {"type":"unsubscribe", ...} and the server replies {"type":"unsubscribe"}
Push data: {"type":"data","data":...}

Address Subscription

Use address to specify one or more addresses. Multiple addresses can be provided in a single request.

{
  "type": "subscribe",
  "address": [
    "0xbadb...",
    "0x0104..."
  ]
}

{
  "type": "unsubscribe",
  "address": [
    "0xbadb...",
    "0x0104..."
  ]
}

Address subscriptions are additive. For example, if 3 addresses are already subscribed and you send 2 more, the total becomes 5.
Subscribing the same address again has no additional effect.

View Connection Stats

Send {"type":"stat"} to view current connection stats:

{
  "type": "stat",
  "data": {
    "addressCount": 8,
    "duration": "6s",
    "sentMsgCount": 42,
    "msgPerSecond": 6.726472859002563,
    "discardedCount": 0,
    "queueLen": 0
  }
}

Close Connection

Unsubscribing all addresses does not close the connection. To proactively close the connection, send:

{
  "type": "close"
}

The server will not reply to this message.

Push Message Example

{
  "type": "data",
  "data": {
    "address": "0x31ca...",
    "time": 1763215209696,
    "coin": "ZRO",
    "px": "1.4646",
    "sz": "12",
    "side": "B",
    "startPosition": "-18867.6",
    "dir": "Close Short",
    "closedPnl": "0.08832",
    "hash": "0x5610...",
    "oid": 2361000,
    "crossed": true,
    "fee": "0",
    "tid": 6486724000,
    "feeToken": "USDC",
    "twapId": null
  }
}

Connection

/api/upgrade/v2/hl/ws/fills

wscat -c "wss://open.bbx.com/api/upgrade/v2/hl/ws/fills?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE"

WS/api/upgrade/v2/hl/ws/filled-orders

WebSocket: Subscribe to User Filled Orders

Subscribes to user filled orders (filled-orders) and supports multiple addresses.

Subscribe and Unsubscribe

The message protocol for subscribe/unsubscribe, stat stats, and close connection is identical to /api/upgrade/v2/hl/ws/fills.

Address subscription example:

{
  "type": "subscribe",
  "address": [
    "0xf048...",
    "0x0104..."
  ]
}

Push Message Example

{
  "type": "data",
  "data": {
    "ts": 1763300544139,
    "address": "0xf048...",
    "hash": "",
    "builder": "",
    "builderF": "0",
    "status": "filled",
    "coin": "BTC",
    "side": "B",
    "limitPx": "95263",
    "sz": "0",
    "oid": 2372804000,
    "placeTs": 1763300530579,
    "trigger": "N/A",
    "isTrigger": false,
    "triggerPx": "0",
    "children": [],
    "positionTpsl": false,
    "reduceOnly": false,
    "orderType": "Limit",
    "origSz": "0.00011",
    "tif": "Alo",
    "cloid": "0xf1d..."
  }
}

Connection

/api/upgrade/v2/hl/ws/filled-orders

wscat -c "wss://open.bbx.com/api/upgrade/v2/hl/ws/filled-orders?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE"

WS/api/upgrade/v2/hl/ws/clearinghouse-state

WebSocket: Subscribe to User Account State

Subscribes to user account state (clearinghouseState) and supports multiple addresses.

Query Parameters

Name
dex
Type
string
Description
Optional. Specify dex; defaults to the primary dex (empty string). One connection supports one dex. Use multiple connections for multiple dex values (?dex=xyz).

Subscribe and Unsubscribe

The message protocol for subscribe/unsubscribe, stat stats, and close connection is identical to /api/upgrade/v2/hl/ws/fills.

One connection supports only one dex. To subscribe to multiple dex values, create multiple connections and pass different dex values in the connection query string.

Address Subscription Example

{
  "type": "subscribe",
  "address": [
    "0xb104xx",
    "0x0104..."
  ]
}

Push Message Example

{
  "channel": "clearinghouseState",
  "data": {
    "address": "0xb104xx",
    "state": {
      "marginSummary": {
        "accountValue": "121494005.579362005",
        "totalNtlPos": "17403841.3265889995",
        "totalRawUsd": "118459535.708464995",
        "totalMarginUsed": "870192.066275"
      },
      "crossMarginSummary": {
        "accountValue": "121494005.579362005",
        "totalNtlPos": "17403841.3265889995",
        "totalRawUsd": "118459535.708464995",
        "totalMarginUsed": "870192.066275"
      },
      "crossMaintenanceMarginUsed": "174038.413194",
      "withdrawable": "119753621.446747005",
      "assetPositions": [
        {
          "type": "oneWay",
          "position": {
            "coin": "BTC",
            "szi": "28.33636",
            "leverage": {
              "type": "cross",
              "value": 20,
              "rawUsd": null
            },
            "entryPx": "71221.7",
            "positionValue": "1995673.1620799999",
            "unrealizedPnl": "-22491.789509",
            "returnOnEquity": "-0.2228934705",
            "liquidationPx": null,
            "marginUsed": "99783.658104",
            "maxLeverage": 50,
            "cumFunding": {
              "allTime": "-620193.219711",
              "sinceOpen": "13300.036167",
              "sinceChange": "0"
            }
          }
        }
      ],
      "time": 1772790208806
    }
  }
}

Connection

/api/upgrade/v2/hl/ws/clearinghouse-state

wscat -c "wss://open.bbx.com/api/upgrade/v2/hl/ws/clearinghouse-state?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE"

GET/api/upgrade/v2/hl/tickers

Get Fills by Order ID

Fetches fill records for the specified order ID (oid), sorted by time.

Path Parameters

Name
oid
Type
string
Description
Order ID, e.g. 2361000

Request Parameters

Name
AccessKeyId
Type
string
Description
Access key ID
Name
SignatureNonce
Type
string
Description
Signature nonce
Name
Timestamp
Type
string
Description
Request timestamp (seconds). Valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" indicates success.
Name
msg
Type
string
Description
Response message
Name
data
Type
array
Description
Array of fill records

Request

GET

/api/upgrade/v2/hl/fills/oid/:oid

curl -G https://open.bbx.com/api/upgrade/v2/hl/fills/oid/2361000 \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "coin": "ETH",
      "side": "buy",
      "price": "2500.30",
      "size": "1.5",
      "time": 1704355200000,
      "oid": 2361000
    }
  ]
}

GET/api/upgrade/v2/hl/fills/twapid/:twapid

Get Fills by TWAP ID

Fetches fill records for the specified TWAP ID (twapId), sorted by time.

Path Parameters

Name
twapid
Type
string
Description
TWAP ID, e.g. 1509340

Request Parameters

Name
AccessKeyId
Type
string
Description
Access key ID
Name
SignatureNonce
Type
string
Description
Signature nonce
Name
Timestamp
Type
string
Description
Request timestamp (seconds). Valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" indicates success.
Name
msg
Type
string
Description
Response message
Name
data
Type
array
Description
Array of fill records

Request

GET

/api/upgrade/v2/hl/fills/twapid/:twapid

curl -G https://open.bbx.com/api/upgrade/v2/hl/fills/twapid/1509340 \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "coin": "XRP",
      "side": "B",
      "px": "2.0418",
      "sz": "33",
      "time": 1768254978060,
      "twapId": 1509340
    }
  ]
}

GET/api/upgrade/v2/hl/fills/builder/:builder/latest

Get Top Trades

Queries the most recent Top N trades, sorted by trade value.

Query Parameters

Name
interval
Type
string
Description
Required. Time window. Range: 1s ~ 7d
Name
coin
Type
string
Description
Required. Filter by coin, e.g. BTC, ETH
Name
limit
Type
integer
Description
Required. Max number of records to return. Default 10, max 100.

Request Parameters

Name
AccessKeyId
Type
string
Description
Access key ID
Name
SignatureNonce
Type
string
Description
Signature nonce
Name
Timestamp
Type
string
Description
Request timestamp (seconds). Valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" indicates success.
Name
msg
Type
string
Description
Response message
Name
data
Type
array
Description
Array of top trade records

Request

GET

/api/upgrade/v2/hl/fills/top-trades

curl -G "https://open.bbx.com/api/upgrade/v2/hl/fills/top-trades?interval=4h&coin=ETH&limit=10" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "time": 1770519070989,
      "address": "0x61ceefxx",
      "coin": "ETH",
      "side": "A",
      "oid": 31541321,
      "isTaker": true,
      "px": "2088.173291377",
      "sz": "2448.34",
      "val": "5112558.19621",
      "endPosition": "1487.685"
    }
  ]
}

GET/api/upgrade/v2/hl/filled-orders/:address/latest

Get Filled Orders

Fetches the latest filled orders for the specified address, sorted in reverse chronological order.

Path Parameters

Name
address
Type
string
Description
User wallet address, e.g. 0x0089xxx

Query Parameters

Name
coin
Type
string
Description
Optional. Filter by coin, e.g. ETH, BTC
Name
limit
Type
integer
Description
Optional. Max number of records to return. Default 1000, max 1000.

Request Parameters

Name
AccessKeyId
Type
string
Description
Access key ID
Name
SignatureNonce
Type
string
Description
Signature nonce
Name
Timestamp
Type
string
Description
Request timestamp (seconds). Valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" indicates success.
Name
msg
Type
string
Description
Response message
Name
data
Type
array
Description
Array of filled orders

Request

GET

/api/upgrade/v2/hl/filled-orders/:address/latest

curl -G "https://open.bbx.com/api/upgrade/v2/hl/filled-orders/0x0089xxx/latest?coin=ETH&limit=1000" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "oid": "23671238460",
      "coin": "ETH",
      "side": "buy",
      "price": "2500.30",
      "size": "1.5",
      "filledSize": "1.5",
      "status": "filled",
      "time": 1704355200000
    }
  ]
}

GET/api/upgrade/v2/hl/filled-orders/oid/:oid

Get Filled Order by Order ID

Fetches the filled order details for the specified order ID (oid). Returns null if it does not exist or is not filled.

Path Parameters

Name
oid
Type
string
Description
Order ID, e.g. 23671238460

Request Parameters

Name
AccessKeyId
Type
string
Description
Access key ID
Name
SignatureNonce
Type
string
Description
Signature nonce
Name
Timestamp
Type
string
Description
Request timestamp (seconds). Valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" indicates success.
Name
msg
Type
string
Description
Response message
Name
data
Type
object
Description
Filled order details. Returns null if it does not exist.

Request

GET

/api/upgrade/v2/hl/filled-orders/oid/:oid

curl -G https://open.bbx.com/api/upgrade/v2/hl/filled-orders/oid/23671238460 \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "oid": "23671238460",
    "coin": "ETH",
    "side": "buy",
    "price": "2500.30",
    "size": "1.5",
    "filledSize": "1.5",
    "status": "filled",
    "time": 1704355200000
  }
}

GET/api/upgrade/v2/hl/orders/:address/latest

Get Order by Order ID

Fetches order details for the specified order ID (oid). Returns null if it does not exist or is not filled.

Path Parameters

Name
oid
Type
string
Description
Order ID, e.g. 23671238460

Request Parameters

Name
AccessKeyId
Type
string
Description
Access key ID
Name
SignatureNonce
Type
string
Description
Signature nonce
Name
Timestamp
Type
string
Description
Request timestamp (seconds). Valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" indicates success.
Name
msg
Type
string
Description
Response message
Name
data
Type
object
Description
Order details. Returns null if it does not exist.

Request

GET

/api/upgrade/v2/hl/orders/oid/:oid

curl -G https://open.bbx.com/api/upgrade/v2/hl/orders/oid/23671238460 \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "oid": "23671238460",
    "coin": "ETH",
    "side": "buy",
    "price": "2500.30",
    "size": "1.5",
    "filledSize": "1.5",
    "status": "filled",
    "time": 1704355200000
  }
}

GET/api/upgrade/v2/hl/orders/top-open-orders

Get Top Open Orders

Queries the current Top N open orders, sorted by order value (limitPx × sz).

Query Parameters

Name
minVal
Type
string
Description
Optional. Minimum order value filter.
Name
coin
Type
string
Description
Optional. Filter by coin, e.g. BTC, ETH
Name
limit
Type
integer
Description
Optional. Max number of records to return. Default 10, max 100.

Request Parameters

Name
AccessKeyId
Type
string
Description
Access key ID
Name
SignatureNonce
Type
string
Description
Signature nonce
Name
Timestamp
Type
string
Description
Request timestamp (seconds). Valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" indicates success.
Name
msg
Type
string
Description
Response message
Name
data
Type
array
Description
Array of top open orders. distPct is the distance percentage from the latest trade price.

Request

GET

/api/upgrade/v2/hl/orders/top-open-orders

curl -G "https://open.bbx.com/api/upgrade/v2/hl/orders/top-open-orders?minVal=1000000&coin=BTC&limit=10" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "time": 1770302531539,
      "address": "0xab5e6xx",
      "oid": 3128418,
      "coin": "ETH",
      "side": "A",
      "sz": "5724.8734",
      "origSz": "5724.8734",
      "limitPx": "2139.4",
      "val": "12247794.15196",
      "reduceOnly": false,
      "tif": "Alo",
      "distPct": "2.83105022831"
    }
  ]
}

GET/api/upgrade/v2/hl/orders/active-stats

Get Active Order Stats

Fetches current active order stats, including bid/ask order counts, values, and whale order share.

Query Parameters

Name
whaleThreshold
Type
string
Description
Optional. Whale threshold (order value = limitPx × sz).
Name
coin
Type
string
Description
Optional. Filter by coin, e.g. BTC, ETH

Request Parameters

Name
AccessKeyId
Type
string
Description
Access key ID
Name
SignatureNonce
Type
string
Description
Signature nonce
Name
Timestamp
Type
string
Description
Request timestamp (seconds). Valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" indicates success.
Name
msg
Type
string
Description
Response message
Name
data
Type
object
Description
Active order stats. bidValueRatio is the ratio of bid value to total value.

Request

GET

/api/upgrade/v2/hl/orders/active-stats

curl -G "https://open.bbx.com/api/upgrade/v2/hl/orders/active-stats?coin=BTC&whaleThreshold=500000" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "totalCount": 25378,
    "bidCount": 14152,
    "askCount": 11226,
    "bidValue": "345449237.071845",
    "askValue": "318547527.07548",
    "bidValueRatio": "0.5202574104",
    "whaleBidCount": 502,
    "whaleAskCount": 371,
    "whaleBidValue": "252957353.94303",
    "whaleAskValue": "253526361.56739",
    "whaleBidValueRatio": "0.3809617269"
  }
}

GET/api/upgrade/v2/hl/klines-with-taker-vol/:coin/:interval

Get Klines (with Taker Volume)

Get kline (candlestick) data for the specified coin, including taker volume details.

Path Parameters

Name
coin
Type
string
Description
Coin symbol, for example BTC, ETH.
Name
interval
Type
string
Description
Kline interval. Allowed range: 1s to 1w.
Second-level intervals: 1s, 3s, 5s, 10s, 15s, 30s
Minute-level intervals: 1m, 3m, 5m, 10m, 15m, 30m
Hour-level intervals: 1h, 2h, 4h, 8h, 12h
Day/Week intervals: 1d, 1w

Query Parameters

Name
startTime
Type
integer
Description
Optional. Start time (milliseconds timestamp). Historical data is available back to 2025-11-01.
Name
endTime
Type
integer
Description
Optional. End time (milliseconds timestamp).
Name
limit
Type
integer
Description
Optional. Maximum number of records to return. Default 100, max 2000.

Authentication Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Kline records. Each item includes:
- openTime - Open time (milliseconds timestamp)
- tc - Trade count
- size - Base volume
- amount - Quote volume
- tcBuyer - Taker buy trade count
- sizeBuyer - Taker buy base volume
- amountBuyer - Taker buy quote volume
- open - Open price
- high - High price
- low - Low price
- close - Close price

Request

GET

/api/upgrade/v2/hl/klines-with-taker-vol/:coin/:interval

curl -G "https://open.bbx.com/api/upgrade/v2/hl/klines-with-taker-vol/BTC/1h?startTime=1704268800000&limit=10" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "openTime": 1764115200000,
      "tc": 290029,
      "size": "613255.9644",
      "amount": "1820089792.99634",
      "tcBuyer": 155482,
      "sizeBuyer": "292357.6723",
      "amountBuyer": "868932151.13917",
      "open": "2958.9",
      "high": "3043.2",
      "low": "2888",
      "close": "3025.8"
    }
  ]
}

GET/api/upgrade/v2/hl/portfolio/:address/:window

Get Account Value Curve and PNL Curve

Get the account value curve and PNL curve data for the specified time window.

Path Parameters

Name
address
Type
string
Description
Wallet address, for example 0x0089xxx.
Name
window
Type
string
Description
Time window. Allowed values: day, week, month, allTime.

Authentication Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Array of scope blocks (typically one for all and one for perp). Each block includes:
- window (string) - Time window of the block. One of day, week, month, allTime.
- scope (string) - Scope of the block. all aggregates perp plus spot, perp is perp only.
- metrics.accountValueHistory (array) - Mark-to-market account value time series. Each point is { "ts": <ms timestamp>, "v": "<decimal>" }.
- metrics.pnlHistory (array) - PnL delta time series, zeroed to the first point of the window. Each point is { "ts": <ms timestamp>, "v": "<decimal>" }.
- metrics.vlm (string decimal) - Total trading volume in the window.

Request

GET

/api/upgrade/v2/hl/portfolio/:address/:window

curl -G https://open.bbx.com/api/upgrade/v2/hl/portfolio/0x0089xxx/week \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "accountValue": [
      {"time": 1704268800000, "value": "10000.00"},
      {"time": 1704355200000, "value": "10500.00"}
    ],
    "pnl": [
      {"time": 1704268800000, "value": "0.00"},
      {"time": 1704355200000, "value": "500.00"}
    ]
  }
}

GET/api/upgrade/v2/hl/pnls/:address

Batch Get PNL Curves

Batch query PNL curves for multiple addresses for the specified period. This is the batch version of /api/upgrade/v2/hl/pnls/:address.

Request Body Parameters

Name
addresses
Type
array[string]
Description
Address list. Maximum 200 addresses. If exceeded, the first 200 are silently used.
Name
period
Type
integer
Description
Period in days: 1, 7, 30, 0 (0 means all-time).
Name
scope
Type
string
Description
Optional. Scope: all, perp. Default all.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array[object]
Description
One set of PNL curve points per address.

Response Fields

Name
address
Type
string
Description
Wallet address.
Name
pnls
Type
array[object]
Description
PNL curve points for the address.
Name
ts
Type
integer
Description
Timestamp (milliseconds).
Name
v
Type
string
Description
PNL value at the timestamp.

Request

POST

/api/upgrade/v2/hl/batch-pnls

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/batch-pnls?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"addresses":["0xafxx"],"period":7,"scope":"all"}'

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "address": "0xafxx",
      "pnls": [
        {
          "ts": 1773122468960,
          "v": "0"
        },
        {
          "ts": 1773144421662,
          "v": "0.030923"
        }
      ]
    }
  ]
}

GET/api/upgrade/v2/hl/max-drawdown/:address

Get Max Drawdown

Get the maximum drawdown for the specified address over the given period. The drawdown is net-inflow adjusted so deposits and withdrawals do not inflate or deflate the value.

Path Parameters

Name
address
Type
string
Description
Wallet address, for example 0x0089xxx.

Query Parameters

Name
days
Type
integer
Description
Period in days. Allowed values: 1, 7, 30, 60, 90.
Name
scope
Type
string
Description
Optional. Scope of the drawdown. Default perp (only perp is supported).

Authentication Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
Max drawdown data. Fields:
- high.time (string, ISO8601) - Timestamp of the peak account value.
- high.value (string decimal) - Peak account value (perp, mark-to-market).
- low.time (string, ISO8601) - Timestamp of the trough account value.
- low.value (string decimal) - Trough account value (perp, mark-to-market).
- maxDrawdown (string decimal) - Drawdown ratio in [0, 1], net-inflow adjusted.
- netIn (string decimal) - Cumulative net deposits during the window.

Request

GET

/api/upgrade/v2/hl/max-drawdown/:address

curl -G "https://open.bbx.com/api/upgrade/v2/hl/max-drawdown/0x0089xxx?days=7&scope=perp" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "high": {
      "time": "2026-01-06T18:03:29.16Z",
      "value": "2864070.8107409999"
    },
    "low": {
      "time": "2026-01-06T23:33:28.853Z",
      "value": "2081165.6652170001"
    },
    "maxDrawdown": "0.2733539766502646",
    "netIn": "0"
  }
}

POST/api/upgrade/v2/hl/batch-max-drawdown

Batch Get Max Drawdown

Batch query the maximum drawdown for multiple addresses. This is the batch version of /api/upgrade/v2/hl/max-drawdown/:address.

Request Body Parameters

Name
addresses
Type
array[string]
Description
Address list. Maximum 2000 addresses. If exceeded, the first 2000 are silently used.
Name
days
Type
integer
Description
Period in days: 1, 7, 30, 60, 90, or 0 (0 means all-time).
Name
scope
Type
string
Description
Optional. Scope of the drawdown. Default perp (only perp is supported).

Authentication Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Max drawdown list. Each item includes (field names are PascalCase in the response):
- Address (string) - Wallet address, lower-cased.
- High.time (string, ISO8601) - Timestamp of the peak account value.
- High.value (string decimal) - Peak account value (perp, mark-to-market).
- Low.time (string, ISO8601) - Timestamp of the trough account value.
- Low.value (string decimal) - Trough account value (perp, mark-to-market).
- MaxDrawdown (string decimal) - Drawdown ratio in [0, 1], net-inflow adjusted.
- NetIn (string decimal) - Cumulative net deposits during the window.

Request

POST

/api/upgrade/v2/hl/batch-max-drawdown

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/batch-max-drawdown?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": ["0x0089xxx", "0x1234xxx"],
    "days": 7,
    "scope": "perp"
  }'

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "Address": "0x0089xxx",
      "High": {
        "time": "2026-01-06T18:03:29.16Z",
        "value": "2864070.8107409999"
      },
      "Low": {
        "time": "2026-01-06T23:33:28.853Z",
        "value": "2081165.6652170001"
      },
      "MaxDrawdown": "0.2733539766502646",
      "NetIn": "0"
    },
    {
      "Address": "0x1234xxx",
      "High": {
        "time": "2026-01-05T10:00:00.00Z",
        "value": "1000000"
      },
      "Low": {
        "time": "2026-01-06T12:00:00.00Z",
        "value": "800000"
      },
      "MaxDrawdown": "0.2",
      "NetIn": "50000"
    }
  ]
}

GET/api/upgrade/v2/hl/traders/:address/best-trades

Get Best Trades (Highest PnL)

Get the list of completed trades (positions) with the highest PnL within the specified period.

Path Parameters

Name
address
Type
string
Description
Wallet address, for example 0xfe00xxx.

Query Parameters

Name
period
Type
integer
Description
Period in days, for example 1, 7, 30.
Name
limit
Type
integer
Description
Maximum number of records to return. Default 10, max 100.

Authentication Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Best trades list.

Request

GET

/api/upgrade/v2/hl/traders/:address/best-trades

curl -G "https://open.bbx.com/api/upgrade/v2/hl/traders/0xfe00xxx/best-trades?limit=10&period=30" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "coin": "ETH",
      "side": "long",
      "entryPrice": "2400.00",
      "exitPrice": "2600.00",
      "pnl": "2000.00",
      "pnlPercent": "8.33",
      "openTime": 1704268800000,
      "closeTime": 1704355200000
    }
  ]
}

GET/api/upgrade/v2/hl/traders/:address/performance-by-coin

Get Performance by Coin

Get per-coin statistics for completed trades within the specified period.

Path Parameters

Name
address
Type
string
Description
Wallet address, for example 0xfe00xxx.

Query Parameters

Name
period
Type
integer
Description
Period in days, for example 1, 7, 30. 0 means all time.
Name
limit
Type
integer
Description
Maximum number of records to return. Default 10, max 100.

Authentication Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Per-coin trade performance data.

Request

GET

/api/upgrade/v2/hl/traders/:address/performance-by-coin

curl -G "https://open.bbx.com/api/upgrade/v2/hl/traders/0xfe00xxx/performance-by-coin?limit=10&period=7" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "coin": "ETH",
      "tradeCount": 15,
      "winCount": 10,
      "lossCount": 5,
      "winRate": "66.67",
      "totalPnl": "5000.00",
      "avgPnl": "333.33"
    },
    {
      "coin": "BTC",
      "tradeCount": 8,
      "winCount": 5,
      "lossCount": 3,
      "winRate": "62.50",
      "totalPnl": "3000.00",
      "avgPnl": "375.00"
    }
  ]
}

GET/api/upgrade/v2/hl/traders/:address/addr-stat

Get Trading Statistics

Get aggregated statistics for completed trades within the specified period.

Path Parameters

Name
address
Type
string
Description
Wallet address, for example 0xfe00xxx.

Query Parameters

Name
period
Type
integer
Description
Period in days, for example 1, 7, 30. Default 7.

Authentication Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
Trading statistics data. Fields:
- orderCount (integer) - Total filled order count over the period.
- closePosCount (integer) - Number of closed positions.
- avgPosDuration (integer) - Average position duration in seconds.
- winRate (string decimal) - Win rate in [0, 1].
- maxDrawdown (string decimal) - Maximum drawdown in [0, 1], with same semantics as /hl/max-drawdown/:address (net-inflow adjusted).
- totalPnl (string decimal) - Total realized PnL over the period.

Request

GET

/api/upgrade/v2/hl/traders/:address/addr-stat

curl -G "https://open.bbx.com/api/upgrade/v2/hl/traders/0xfe00xxx/addr-stat?period=7" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "avgPosDuration": "3600",
    "closePosCount": 15,
    "maxDrawdown": "0.1234",
    "orderCount": 23,
    "totalPnl": "8000.00",
    "winRate": "0.6522"
  }
}

POST/api/upgrade/v2/hl/traders/batch-addr-stat

Batch Get Trading Statistics

Batch query trading statistics for multiple addresses. This is the batch version of /api/upgrade/v2/hl/traders/:address/addr-stat.

Request Body Parameters

Name
addresses
Type
array[string]
Description
Address list. Maximum 2000 addresses. If exceeded, the first 2000 are silently used.
Name
period
Type
integer
Description
Period in days: 1, 7, 30, 0 (0 means all-time). Default 7.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array[object]
Description
Trading statistics list.

Response Fields

Name
address
Type
string
Description
Wallet address.
Name
winRate
Type
string
Description
Win rate.
Name
orderCount
Type
integer
Description
Filled order count.
Name
closePosCount
Type
integer
Description
Close position count.
Name
avgPosDuration
Type
integer
Description
Average position duration (seconds).
Name
maxDrawdown
Type
string
Description
Maximum drawdown.
Name
totalPnl
Type
string
Description
Total PnL.

Request

POST

/api/upgrade/v2/hl/traders/batch-addr-stat

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/traders/batch-addr-stat?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"addresses":["0xfeeexx","0x5b5d51203a0f9079f8aeb098a6523a13f298c060"],"period":7}'

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "address": "0xfeeexx",
      "winRate": "0.5414634146341464",
      "orderCount": 9662,
      "closePosCount": 205,
      "avgPosDuration": 2910,
      "maxDrawdown": "0.43635643",
      "totalPnl": "1383.985419"
    }
  ]
}

GET/api/upgrade/v2/hl/traders/:address/completed-trades

Get Completed Trades

Query the latest completed trades (positions).

Path Parameters

Name
address
Type
string
Description
Wallet address, for example 0xfe00xxx.

Query Parameters

Name
coin
Type
string
Description
Optional. Filter by coin.
Name
limit
Type
integer
Description
Maximum number of records to return. Default 100, max 2000.

Authentication Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Completed trades list. Each item includes:
- coin (string) - Trading pair, for example BTC, ETH.
- marginMode (string) - cross or isolated.
- direction (string) - long or short.
- size (string decimal) - Average position size.
- entryPrice (string decimal) - Average entry price.
- startTime (string, ISO8601) - Position open time.
- endTime (string, ISO8601) - Position close time.
- closePrice (string decimal) - Average close price.
- totalFee (string decimal) - Cumulative fees.
- pnl (string decimal) - Realized PnL.

Request

GET

/api/upgrade/v2/hl/traders/:address/completed-trades

curl -G "https://open.bbx.com/api/upgrade/v2/hl/traders/0xfe00xxx/completed-trades?limit=2000" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "coin": "ETH",
      "side": "long",
      "entryPrice": "2400.00",
      "exitPrice": "2600.00",
      "size": "10.0",
      "pnl": "2000.00",
      "pnlPercent": "8.33",
      "openTime": 1704268800000,
      "closeTime": 1704355200000
    },
    {
      "coin": "BTC",
      "side": "short",
      "entryPrice": "43000.00",
      "exitPrice": "42500.00",
      "size": "0.5",
      "pnl": "250.00",
      "pnlPercent": "1.16",
      "openTime": 1704182400000,
      "closeTime": 1704268800000
    }
  ]
}

POST/api/upgrade/v2/hl/traders/:address/completed-trades/by-time

Query Completed Trades by Time

Query completed trades (positions) within a time range with pagination. Results are sorted by endTime.

Path Parameters

Name
address
Type
string
Description
Wallet address, for example 0xfe00xxx.

Request Body Parameters

Name
pageNum
Type
integer
Description
Page number. Default 1, max 50.
Name
pageSize
Type
integer
Description
Page size. Default 20, max 2000.
Name
Coin
Type
string
Description
Optional. Filter by coin, for example BTC, ETH.
Name
endTimeFrom
Type
integer
Description
Optional. End time start (milliseconds timestamp).
Name
endTimeTo
Type
integer
Description
Optional. End time end (milliseconds timestamp).

Authentication Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
Paginated data containing list (trades), total (total count), pageNum, and pageSize.

Request

POST

/api/upgrade/v2/hl/traders/:address/completed-trades/by-time

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/traders/0xfeee942a06d2f8012823ccde7bf7bcbcaa29a09f/completed-trades/by-time?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "pageNum": 2,
    "pageSize": 10,
    "Coin": "BTC",
    "endTimeFrom": 1771891200000,
    "endTimeTo": 1772064000000
  }'

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "list": [
      {
        "coin": "BTC",
        "side": "long",
        "entryPrice": "43000.00",
        "exitPrice": "45000.00",
        "size": "1.0",
        "pnl": "2000.00",
        "pnlPercent": "4.65",
        "openTime": 1771891200000,
        "closeTime": 1771977600000
      }
    ],
    "total": 25,
    "pageNum": 2,
    "pageSize": 10
  }
}

GET/api/upgrade/v2/hl/traders/:address/current-position-history/:coin

Get Current Position History

Get history for the current position of the specified coin. If there is no current position, returns data: null.

Path Parameters

Name
address
Type
string
Description
Wallet address, for example 0xfe00xxx.
Name
coin
Type
string
Description
Coin symbol, for example BTC, ETH.

Authentication Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
Current position history data.

Request

GET

/api/upgrade/v2/hl/traders/:address/current-position-history/:coin

curl -G "https://open.bbx.com/api/upgrade/v2/hl/traders/0xfe00xxx/current-position-history/BTC" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "address": "0x9ec000",
    "coin": "BTC",
    "direction": "long",
    "cross": true,
    "startTime": "2026-02-06T23:15:46.098Z",
    "history": [
      {
        "time": 1770419747107,
        "size": "0.00016",
        "leverage": 40,
        "effLeverage": null,
        "entryPrice": "70898",
        "positionValue": "11.34368",
        "unrealizedPnl": "0",
        "returnOnEquity": "0",
        "liqPrice": null,
        "marginUsed": "0.283592",
        "cumFunding": "0"
      }
    ]
  }
}

GET/api/upgrade/v2/hl/traders/:address/completed-position-history/:coin

Get Completed Position History

Get history for a completed position of the specified coin and time range. If the position cannot be found, returns a 400 error. At least one of startTime or endTime must be provided.

Note: startTime and endTime must be obtained from the responses of the following endpoints to locate the historical position:

Get completed trades (/hl/traders/:address/completed-trades): openTime / closeTime
Query completed trades by time (/hl/traders/:address/completed-trades/by-time): openTime / closeTime

Path Parameters

Name
address
Type
string
Description
Wallet address, for example 0xfe00xxx.
Name
coin
Type
string
Description
Coin symbol, for example BTC, ETH.

Query Parameters

Name
startTime
Type
integer
Description
Start timestamp (milliseconds). At least one of startTime/endTime is required.
Name
endTime
Type
integer
Description
End timestamp (milliseconds). At least one of startTime/endTime is required.

Authentication Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
Completed position history data. Compared to the current position history endpoint, this includes an additional endTime field. Fields:
- address (string) - Wallet address.
- coin (string) - Trading pair.
- direction (string) - long or short.
- cross (bool) - true for cross margin, false for isolated.
- startTime (string, ISO8601) - Position open time.
- endTime (string, ISO8601, nullable) - Position close time; absent while the position is still open.
- history (array) - Snapshots of each size/leverage/entry change during the position lifecycle. Each item includes:
  - time (integer ms timestamp) - Snapshot timestamp.
  - size (string decimal) - Position size at the snapshot.
  - entryPx (string decimal) - Entry price at the snapshot.
  - leverage (integer) - Leverage multiple.
  - marginUsed (string decimal) - Margin held for the position.
  - unrealizedPnl (string decimal) - Unrealized PnL.
  - liquidationPx (string decimal, nullable) - Liquidation price.

Request

GET

/api/upgrade/v2/hl/traders/:address/completed-position-history/:coin

curl -G "https://open.bbx.com/api/upgrade/v2/hl/traders/0xfe00xxx/completed-position-history/BTC?startTime=1770000000000&endTime=1770620000000" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "address": "0x9ec000",
    "coin": "BTC",
    "direction": "long",
    "cross": true,
    "startTime": "2026-02-06T23:15:46.098Z",
    "endTime": "2026-02-08T12:00:00.000Z",
    "history": [
      {
        "time": 1770419747107,
        "size": "0.00016",
        "leverage": 40,
        "entryPrice": "70898",
        "positionValue": "11.34368",
        "unrealizedPnl": "0",
        "returnOnEquity": "0",
        "marginUsed": "0.283592",
        "cumFunding": "0"
      }
    ]
  }
}

GET/api/upgrade/v2/hl/traders/:address/current-position-pnl/:coin

Get Current Position PnL

Get the PnL history for the current position of the specified coin, aggregated by interval. If there is no current position, returns data: null.

Path Parameters

Name
address
Type
string
Description
Wallet address, for example 0xfe00xxx.
Name
coin
Type
string
Description
Coin symbol, for example BTC, ETH.

Query Parameters

Name
interval
Type
string
Description
Optional. Aggregation interval. Allowed range: 15m to 1d.
Name
limit
Type
integer
Description
Optional. Maximum number of records to return. Default 20, max 1000.

Authentication Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
Current position PnL data.

Request

GET

/api/upgrade/v2/hl/traders/:address/current-position-pnl/:coin

curl -G "https://open.bbx.com/api/upgrade/v2/hl/traders/0xfe00xxx/current-position-pnl/BTC?interval=4h&limit=10" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "address": "0x9ec000",
    "coin": "BTC",
    "direction": "long",
    "cross": true,
    "startTime": "2026-02-06T23:15:46.098Z",
    "interval": "4h",
    "pnls": [
      {
        "time": 1770465600000,
        "size": "0.22452",
        "positionValue": "15356.71896",
        "unrealizedPnl": "-227.356711"
      }
    ]
  }
}

GET/api/upgrade/v2/hl/traders/:address/completed-position-pnl/:coin

Get the PnL history for a completed position of the specified coin and time range, aggregated by interval. If the position cannot be found, returns a 400 error. At least one of startTime or endTime must be provided.

Note: startTime and endTime must be obtained from the responses of the following endpoints to locate the historical position:

Get completed trades (/hl/traders/:address/completed-trades): openTime / closeTime
Query completed trades by time (/hl/traders/:address/completed-trades/by-time): openTime / closeTime

Path Parameters

Name
address
Type
string
Description
Wallet address, for example 0xfe00xxx.
Name
coin
Type
string
Description
Coin symbol, for example BTC, ETH.

Query Parameters

Name
interval
Type
string
Description
Optional. Aggregation interval. Allowed range: 15m to 1d.
Name
startTime
Type
integer
Description
Start timestamp (milliseconds). At least one of startTime/endTime is required.
Name
endTime
Type
integer
Description
End timestamp (milliseconds). At least one of startTime/endTime is required.
Name
limit
Type
integer
Description
Optional. Maximum number of records to return. Default 20, max 1000.

Authentication Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
Completed position PnL data. Compared to the current position PnL endpoint, this includes an additional endTime field.

Request

GET

/api/upgrade/v2/hl/traders/:address/completed-position-pnl/:coin

curl -G "https://open.bbx.com/api/upgrade/v2/hl/traders/0xfe00xxx/completed-position-pnl/BTC?interval=4h&startTime=1770000000000&endTime=1770620000000&limit=10" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "address": "0x9ec000",
    "coin": "BTC",
    "direction": "long",
    "cross": true,
    "startTime": "2026-02-06T23:15:46.098Z",
    "endTime": "2026-02-08T12:00:00.000Z",
    "interval": "4h",
    "pnls": [
      {
        "time": 1770465600000,
        "size": "0.22452",
        "positionValue": "15356.71896",
        "unrealizedPnl": "-227.356711"
      }
    ]
  }
}

GET/api/upgrade/v2/hl/traders/:address/current-position-executions/:coin

Get Current Position Executions

Get aggregated executions for the current position of the specified coin. If there is no current position, returns data: null.

Path Parameters

Name
address
Type
string
Description
Wallet address, for example 0xfe00xxx.
Name
coin
Type
string
Description
Coin symbol, for example BTC, ETH.

Query Parameters

Name
interval
Type
string
Description
Optional. Aggregation interval. Allowed range: 15m to 1d.
Name
limit
Type
integer
Description
Optional. Maximum number of records to return. Default 20, max 1000.

Authentication Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
Current position executions data.

Request

GET

/api/upgrade/v2/hl/traders/:address/current-position-executions/:coin

curl -G "https://open.bbx.com/api/upgrade/v2/hl/traders/0xfe00xxx/current-position-executions/BTC?interval=4h&limit=10" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "address": "0x9ec000",
    "coin": "BTC",
    "direction": "long",
    "cross": true,
    "startTime": "2026-02-06T23:15:46.098Z",
    "interval": "4h",
    "executions": [
      {
        "time": 1770465600000,
        "buyCount": 309,
        "sellCount": 1,
        "buySz": "0.04749",
        "sellSz": "0.02256",
        "buyAvgPx": "69025.5129500947",
        "sellAvgPx": null
      }
    ]
  }
}

GET/api/upgrade/v2/hl/traders/:address/completed-position-executions/:coin

Get Completed Position Executions

Get aggregated executions for a completed position. If the position cannot be found, returns a 400 error. At least one of startTime or endTime must be provided.

Note: startTime and endTime must be obtained from the responses of the following endpoints to locate the historical position:

Get completed trades (/hl/traders/:address/completed-trades): openTime / closeTime
Query completed trades by time (/hl/traders/:address/completed-trades/by-time): openTime / closeTime

Path Parameters

Name
address
Type
string
Description
Wallet address, for example 0xfe00xxx.
Name
coin
Type
string
Description
Coin symbol, for example BTC, ETH.

Query Parameters

Name
interval
Type
string
Description
Optional. Aggregation interval. Allowed range: 15m to 1d.
Name
startTime
Type
integer
Description
Start timestamp (milliseconds). At least one of startTime/endTime is required.
Name
endTime
Type
integer
Description
End timestamp (milliseconds). At least one of startTime/endTime is required.
Name
limit
Type
integer
Description
Optional. Maximum number of records to return. Default 20, max 1000.

Authentication Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
Completed position executions data.

Request

GET

/api/upgrade/v2/hl/traders/:address/completed-position-executions/:coin

curl -G "https://open.bbx.com/api/upgrade/v2/hl/traders/0xfe00xxx/completed-position-executions/BTC?interval=4h&startTime=1770000000000&endTime=1770620000000&limit=10" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "address": "0x9ec000",
    "coin": "BTC",
    "direction": "long",
    "cross": true,
    "startTime": "2026-02-06T23:15:46.098Z",
    "endTime": "2026-02-08T12:00:00.000Z",
    "interval": "4h",
    "executions": [
      {
        "time": 1770465600000,
        "buyCount": 309,
        "sellCount": 1,
        "buySz": "0.04749",
        "sellSz": "0.02256",
        "buyAvgPx": "69025.5129500947",
        "sellAvgPx": null
      }
    ]
  }
}

POST/api/upgrade/v2/hl/traders/accounts

Batch Query Accounts

Query account information for multiple addresses.

Request Body Parameters

Name
addresses
Type
array
Description
Address list. Maximum 2000 addresses. If exceeded, the first 2000 are silently used.

Authentication Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Account information list.

Request

POST

/api/upgrade/v2/hl/traders/accounts

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/traders/accounts?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      "0xfe00xxx",
      "0xaf72xxx"
    ]
  }'

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "address": "0xfe00xxx",
      "currentPosition": 3,
      "effLeverage": "5.123",
      "lastOperationAt": 1770302542171,
      "leverage": null,
      "marginUsage": "50000.00",
      "marginUsageRate": "0.333",
      "perpValue": "100000.00",
      "spotValue": "50000.00",
      "totalValue": "150000.00"
    }
  ]
}

POST/api/upgrade/v2/hl/traders/statistics

Batch Query Trading Statistics

Query trading statistics for multiple addresses for the specified period.

Request Body Parameters

Name
period
Type
integer
Description
Period in days, for example 1, 7, 30. 0 means all time. Default 7.
Name
pnlList
Type
boolean
Description
Whether to include PnL curve data.
Name
addresses
Type
array
Description
Address list. Maximum 50 addresses. If exceeded, the first 50 are silently used.

Authentication Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Trading statistics list.

Request

POST

/api/upgrade/v2/hl/traders/statistics

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/traders/statistics?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "period": 7,
    "pnlList": false,
    "addresses": [
      "0xfe00xxx",
      "0xaf72xxx"
    ]
  }'

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "address": "0xfe00xxx",
      "avgHoldingSec": 16522,
      "currentPosition": 10,
      "effLeverage": "9.63",
      "lastOperationAt": 1770302542171,
      "leverage": null,
      "longPnl": "11471.623794",
      "longWr": "1",
      "marginUsage": "77645.888329",
      "marginUsageRate": "0.6038",
      "perpValue": "128593.132716",
      "pnlList": null,
      "positions": 47,
      "profitPositions": 47,
      "realizedPnl": "13672.918609",
      "shortPnl": "11471.623794",
      "shortWr": "1",
      "spotValue": "39161.07",
      "totalValue": "167754.21",
      "winRate": "1"
    }
  ]
}

POST/api/upgrade/v2/hl/traders/clearinghouse-state

Batch Get Perp Account State

Batch get perp account state for multiple addresses. This is equivalent to the multi-address version of type=clearinghouseState in POST /info.

Request Body Parameters

Name
addresses
Type
array
Description
Required. Address list. Maximum 2000 addresses. If exceeded, the first 2000 are silently used.
Name
dex
Type
string
Description
Optional. DEX name. Default empty string means the primary DEX.

Authentication Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Account state list.
Name
data[].address
Type
string
Description
Address.
Name
data[].state
Type
object
Description
Account state details.
Name
data[].state.marginSummary
Type
object
Description
Margin summary.
Name
data[].state.marginSummary.accountValue
Type
string
Description
Account value.
Name
data[].state.marginSummary.totalNtlPos
Type
string
Description
Total notional position value.
Name
data[].state.marginSummary.totalRawUsd
Type
string
Description
Total raw USD.
Name
data[].state.marginSummary.totalMarginUsed
Type
string
Description
Total margin used.
Name
data[].state.crossMarginSummary
Type
object
Description
Cross margin summary.
Name
data[].state.crossMaintenanceMarginUsed
Type
string
Description
Cross maintenance margin used.
Name
data[].state.withdrawable
Type
string
Description
Withdrawable amount.
Name
data[].state.assetPositions
Type
array
Description
Position list. Each item is { "type": "oneWay", "position": { ... } }, where position has:
- coin (string) - Coin symbol, for example BTC.
- szi (string decimal) - Signed size. Positive means long, negative means short.
- leverage.type (string) - cross or isolated.
- leverage.value (integer) - Leverage multiple.
- leverage.rawUsd (string decimal or null) - Raw USD margin for isolated leverage; null for cross.
- entryPx (string decimal) - Average entry price.
- positionValue (string decimal) - Mark-to-market notional of the position.
- unrealizedPnl (string decimal) - Unrealized PnL.
- returnOnEquity (string decimal) - ROE on margin.
- liquidationPx (string decimal or null) - Liquidation price.
- marginUsed (string decimal) - Margin held for this position.
- maxLeverage (integer) - Maximum leverage allowed for the coin.
- cumFunding.allTime (string decimal) - Cumulative funding since position inception.
- cumFunding.sinceOpen (string decimal) - Cumulative funding since the current open.
- cumFunding.sinceChange (string decimal) - Cumulative funding since the last size change.
Name
data[].state.time
Type
integer
Description
Timestamp (milliseconds).

Request

POST

/api/upgrade/v2/hl/traders/clearinghouse-state

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/traders/clearinghouse-state?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      "0xfe00xxx",
      "0xaf72xxx"
    ],
    "dex": ""
  }'

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "address": "0xaf72xxx",
      "state": {
        "marginSummary": {
          "accountValue": "18755.769289",
          "totalNtlPos": "20822.33631",
          "totalRawUsd": "39578.105599",
          "totalMarginUsed": "1041.116815"
        },
        "crossMarginSummary": {
          "accountValue": "18755.769289",
          "totalNtlPos": "20822.33631",
          "totalRawUsd": "39578.105599",
          "totalMarginUsed": "1041.116815"
        },
        "crossMaintenanceMarginUsed": "260.279203",
        "withdrawable": "16673.535658",
        "assetPositions": [
          {
            "type": "oneWay",
            "position": {
              "coin": "BTC",
              "szi": "-0.30291",
              "leverage": {
                "type": "cross",
                "value": 20,
                "rawUsd": null
              },
              "entryPx": "68852.8",
              "positionValue": "20822.33631",
              "unrealizedPnl": "33.88779",
              "returnOnEquity": "0.0324965726",
              "liquidationPx": "129046.538613311",
              "marginUsed": "1041.116815",
              "maxLeverage": 40,
              "cumFunding": {
                "allTime": "-1291.262616",
                "sinceOpen": "0",
                "sinceChange": "0"
              }
            }
          }
        ],
        "time": 1772503181102
      }
    }
  ]
}

POST/api/upgrade/v2/hl/traders/spot-clearinghouse-state

Batch Get Spot Account State

Batch get spot account state for multiple addresses. This is equivalent to the multi-address version of type=spotClearinghouseState in POST /info.

Request Body Parameters

Name
addresses
Type
array
Description
Required. Address list. Maximum 2000 addresses. If exceeded, the first 2000 are silently used.

Authentication Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Account state list.
Name
data[].address
Type
string
Description
Address.
Name
data[].spotState
Type
object
Description
Spot account state.
Name
data[].spotState.balances
Type
array
Description
Balance list.
Name
data[].spotState.balances[].coin
Type
string
Description
Coin.
Name
data[].spotState.balances[].token
Type
integer
Description
Token ID.
Name
data[].spotState.balances[].total
Type
string
Description
Total amount.
Name
data[].spotState.balances[].hold
Type
string
Description
Amount on hold.
Name
data[].spotState.balances[].entryNtl
Type
string
Description
Entry notional.

Request

POST

/api/upgrade/v2/hl/traders/spot-clearinghouse-state

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/traders/spot-clearinghouse-state?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      "0xfe00xxx",
      "0xaf72xxx"
    ]
  }'

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "address": "0xfe00xxx",
      "spotState": {
        "balances": [
          {
            "coin": "USDC",
            "token": 0,
            "total": "0",
            "hold": "0",
            "entryNtl": "0"
          }
        ]
      }
    },
    {
      "address": "0xaf72xxx",
      "spotState": {
        "balances": [
          {
            "coin": "USDC",
            "token": 0,
            "total": "0.00000996",
            "hold": "0",
            "entryNtl": "0"
          },
          {
            "coin": "NBT",
            "token": 382,
            "total": "0.03988497",
            "hold": "0",
            "entryNtl": "0.00008324"
          }
        ]
      }
    }
  ]
}

GET/api/upgrade/v2/hl/ledger-updates/net-flow/:address

Get Ledger Net Flow

Get the user's net deposits over the selected period, split into perp-account net flow and spot-account net flow.

Path Parameters

Name
address
Type
string
Description
User wallet address, e.g. 0x0089xxx

Query Parameters

Name
days
Type
integer
Description
Optional. Days to aggregate. Allowed values: 1, 7, 30, 60, 90

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
Ledger net flow data. Fields:
- address (string) - Wallet address.
- netPerpIn (string decimal) - Net USD deposits into the perp account during the window.
- netSpotIn (string decimal) - Net USD deposits into the spot account during the window.

Request

GET

/api/upgrade/v2/hl/ledger-updates/net-flow/:address

curl -G "https://open.bbx.com/api/upgrade/v2/hl/ledger-updates/net-flow/0x0089xxx?days=7" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "netPerpIn": "0",
    "netSpotIn": "-8355.58027"
  }
}

POST/api/upgrade/v2/hl/ledger-updates/batch-net-flow

Batch Get Ledger Net Flow

Batch get net deposits for multiple addresses over the selected period, split into perp-account net flow and spot-account net flow.

Request Parameters

Name
addresses
Type
array
Description
Address list. Up to 2,000 addresses. If more are provided, the extra entries are silently truncated (only the first 2,000 are used).
Name
days
Type
integer
Description
Optional. Days to aggregate. Allowed values: 1, 7, 30, 60, 90, 0 (0 means all-time).

Authentication Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Ledger net flow list. Each item includes:
- address (string) - Wallet address.
- netPerpIn (string decimal) - Net USD deposits into the perp account during the window.
- netSpotIn (string decimal) - Net USD deposits into the spot account during the window.

Request

POST

/api/upgrade/v2/hl/ledger-updates/batch-net-flow

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/ledger-updates/batch-net-flow?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": ["0x0089xxx", "0x1234xxx"],
    "days": 7
  }'

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "address": "0x0089xxx",
      "netPerpIn": "0",
      "netSpotIn": "-8355.58027"
    },
    {
      "address": "0x1234xxx",
      "netPerpIn": "50000",
      "netSpotIn": "10000"
    }
  ]
}

GET/api/upgrade/v2/hl/open-interest/summary

Get Current Open Interest Summary

Get the current open interest summary for the entire market.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
Open interest summary, including positionCount, longPv, shortPv, totalPv, and avgPv.

Request

GET

/api/upgrade/v2/hl/open-interest/summary

curl -G "https://open.bbx.com/api/upgrade/v2/hl/open-interest/summary" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "positionCount": 211694,
    "longPv": "2481509687.2189629948",
    "shortPv": "2333089812.667876",
    "totalPv": "4814599499.8868389948",
    "avgPv": "22780.220013659"
  }
}

GET/api/upgrade/v2/hl/open-interest/top-coins

Get Top Coins Open Interest Summary

Get the current open interest summary for top coins, sorted by totalPv.

Query Parameters

Name
limit
Type
integer
Description
Optional. Number of coins to return. Default 10, max 50.
Name
interval
Type
string
Description
Lookback window. Default 3d. Range: 15m to 180d.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Per-coin open interest summary array.

Request

GET

/api/upgrade/v2/hl/open-interest/top-coins

curl -G "https://open.bbx.com/api/upgrade/v2/hl/open-interest/top-coins?limit=2" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "coin": "BTC",
      "positionCount": 24771,
      "longPv": "646442968.2481799974",
      "shortPv": "607339544.2941900022",
      "totalPv": "1253782512.5423699996",
      "avgPv": "50657.8792946412"
    },
    {
      "coin": "ETH",
      "positionCount": 12845,
      "longPv": "513131037.1366399943",
      "shortPv": "488719066.2714399968",
      "totalPv": "1001850103.4080799911",
      "avgPv": "78135.2443774824"
    }
  ]
}

GET/api/upgrade/v2/hl/accumulated-taker-delta/:coin

Get Accumulated Taker Delta

Query the accumulated taker buy/sell delta for a given coin.

Path Parameters

Name
coin
Type
string
Description
Coin symbol/name, e.g. BTC, ETH.

Query Parameters

Name
interval
Type
string
Description
Optional. Lookback window. Range: 1s to 60d.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
Accumulated taker delta, including szDelta and valDelta.

Request

GET

/api/upgrade/v2/hl/accumulated-taker-delta/:coin

curl -G "https://open.bbx.com/api/upgrade/v2/hl/accumulated-taker-delta/BTC?interval=4h" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "szDelta": "-3814.9315",
    "valDelta": "-7801383.84039"
  }
}

GET/api/upgrade/v2/hl/orderbooks/history-summaries/:coin

Historical Orderbook Summary

Get the historical orderbook summary statistics for a given coin.

Path Parameters

Name
coin
Type
string
Description
Coin symbol/name, e.g. BTC, ETH.

Query Parameters

Name
interval
Type
string
Description
Optional. Lookback window. Default 1d. Range: 1h to 180d.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Data array. Each item contains orderbook summary statistics.

Request

GET

/api/upgrade/v2/hl/orderbooks/history-summaries/:coin

curl -G "https://open.bbx.com/api/upgrade/v2/hl/orderbooks/history-summaries/ETH?interval=4h" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "time": 1704067200,
      "coin": "ETH",
      "bidVolume": "12345.67",
      "askVolume": "12345.67"
    }
  ]
}

GET/api/upgrade/v2/hl/open-interest/history/:coin

Historical Open Interest

Get the historical open interest statistics for a given coin.

Path Parameters

Name
coin
Type
string
Description
Coin symbol/name, e.g. ETH.

Query Parameters

Name
interval
Type
string
Description
Lookback window. Default 3d. Range: 15m to 180d.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Data array. Each item contains:
- time - timestamp
- coin - coin symbol/name
- positionCount - number of positions
- longCount - number of long positions
- longPv - long position value
- totalPv - total position value
- avgPv - average position value

Request

GET

/api/upgrade/v2/hl/open-interest/history/:coin

curl -G "https://open.bbx.com/api/upgrade/v2/hl/open-interest/history/ETH?interval=4h" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "time": 1772081640000,
      "coin": "ETH",
      "positionCount": 12366,
      "longCount": 6204,
      "longPv": "637779000.95540001",
      "totalPv": "1229888700.43613002",
      "avgPv": "99642.60718108"
    }
  ]
}

Note: Hyperliquid Info API uses a single unified endpoint POST /api/upgrade/v2/hl/info, and the request body field type selects the specific capability.

POST/api/upgrade/v2/hl/info

Unified Info API Endpoint

Hyperliquid Info API uses a unified endpoint and follows the official API format. Use the request body field type to select which data to query.

Request Body Parameters

Name
type
Type
string
Description
Request type. Supported values:
- meta: get perpetual futures metadata
- spotMeta: get spot metadata
- clearinghouseState: get user's perp account state (requires user)
- spotClearinghouseState: get user's spot account state (requires user)
- openOrders: get user's open orders (requires user)
- frontendOpenOrders: get user's open orders (frontend-friendly format, requires user)
- userFees: get user's fee rates (requires user)
- userFills: get user's fills (requires user)
- userFillsByTime: get user's fills in a time range (requires user, startTime)
- candleSnapshot: get candlestick data (requires req)
- perpDexs: get perpetual DEX list
- historicalOrders: get historical orders (requires user)
- orderStatus: get order status (requires user, oid)
- userFunding: get user's funding history (requires user, startTime)
- userNonFundingLedgerUpdates: get user's non-funding ledger updates (requires user, startTime)
- portfolio: get user's portfolio (requires user)
- webData2: get web aggregated data (requires user)
- userTwapSliceFills: get user's TWAP slice fills (requires user)
- activeAssetData: get active asset data (requires user, coin)
- allMids: get all mid prices
- l2Book: get L2 orderbook (requires coin)
Name
user
Type
string
Description
User wallet address. Required for some type values.
Name
startTime
Type
integer
Description
Start time (milliseconds). Required for some type values.
Name
endTime
Type
integer
Description
End time (milliseconds). Optional.
Name
coin
Type
string
Description
Coin symbol/name. Required for some type values.
Name
oid
Type
integer|string
Description
Order ID. Required for orderStatus.
Name
dex
Type
string
Description
DEX name. Optional for frontendOpenOrders.
Name
aggregateByTime
Type
boolean
Description
Whether to aggregate by time. Optional for userFills / userFillsByTime.
Name
req
Type
object
Description
Request object used by candleSnapshot, including coin, interval, startTime, endTime.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object|array
Description
Response payload. The shape depends on type.

Request Examples

POST

/api/upgrade/v2/hl/info

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/info?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"type": "meta"}'

Response Example (meta)

{
  "code": "0",
  "msg": "success",
  "data": {
    "universe": [
      {
        "name": "BTC",
        "szDecimals": 5,
        "maxLeverage": 50
      },
      {
        "name": "ETH",
        "szDecimals": 4,
        "maxLeverage": 50
      }
    ]
  }
}

POST/api/upgrade/v2/hl/info

Get Spot Metadata

Get Hyperliquid spot trading metadata, including the list of tradable tokens, spot pairs, and related info.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
Spot metadata.

Request

POST

/api/upgrade/v2/hl/info

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/info?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"type":"spotMeta"}'

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "universe": [
      {
        "tokens": [
          {"name": "USDC", "szDecimals": 6, "weiDecimals": 6, "index": 0},
          {"name": "PURR", "szDecimals": 0, "weiDecimals": 18, "index": 1}
        ],
        "name": "PURR/USDC",
        "index": 0
      }
    ]
  }
}

POST/api/upgrade/v2/hl/info

Get User Perp Account State

Get the user's perp account state, including positions, margin usage, account value, and more.

Request Body Parameters

Name
user
Type
string
Description
User wallet address, e.g. 0x0000000000000000000000000000000000000000
Name
dex
Type
string
Description
Optional. DEX name. Default is an empty string, which means the primary DEX.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
User account state payload.

Request

POST

/api/upgrade/v2/hl/info

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/info?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"type":"clearinghouseState","user":"0x0000000000000000000000000000000000000000","dex":""}'

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "assetPositions": [
      {
        "position": {
          "coin": "ETH",
          "entryPx": "2986.3",
          "leverage": {"type": "isolated", "value": 20},
          "liquidationPx": "2866.26936529",
          "marginUsed": "4.967826",
          "positionValue": "100.02765",
          "unrealizedPnl": "-0.0134",
          "szi": "0.0335"
        },
        "type": "oneWay"
      }
    ],
    "marginSummary": {
      "accountValue": "13109.482328",
      "totalMarginUsed": "4.967826",
      "totalNtlPos": "100.02765"
    },
    "withdrawable": "13104.514502"
  }
}

POST/api/upgrade/v2/hl/info

Get User Spot Account State

Get the user's spot account state, including token balances and more.

Request Body Parameters

Name
user
Type
string
Description
User wallet address, e.g. 0x0000000000000000000000000000000000000000

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
User spot account state payload.

Request

POST

/api/upgrade/v2/hl/info

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/info?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"type":"spotClearinghouseState","user": "0x0000000000000000000000000000000000000000"}'

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "balances": [
      {"coin": "USDC", "hold": "0", "total": "1000.00"},
      {"coin": "PURR", "hold": "0", "total": "500"}
    ]
  }
}

POST/api/upgrade/v2/hl/info

Get User Open Orders

Get all current open orders for the user.

Request Body Parameters

Name
user
Type
string
Description
User wallet address.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Open order list.

Request

POST

/api/upgrade/v2/hl/info

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/info?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"type":"openOrders","user": "0x0000000000000000000000000000000000000000"}'

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "coin": "BTC",
      "limitPx": "29792.0",
      "oid": 91490942,
      "side": "A",
      "sz": "5.0",
      "timestamp": 1681247412573
    }
  ]
}

POST/api/upgrade/v2/hl/info

Get User Open Orders (Frontend Format)

Get all current open orders for the user, in a frontend-friendly format with more order details.

Request Body Parameters

Name
user
Type
string
Description
User wallet address.
Name
dex
Type
string
Description
Optional. Perp DEX name. Default is an empty string, which means the first perp DEX and includes spot open orders.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Open order list (frontend format).

Request

POST

/api/upgrade/v2/hl/info

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/info?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"type":"frontendOpenOrders","user": "0x0000000000000000000000000000000000000000", "dex": ""}'

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "coin": "BTC",
      "isPositionTpsl": false,
      "isTrigger": false,
      "limitPx": "29792.0",
      "oid": 91490942,
      "orderType": "Limit",
      "origSz": "5.0",
      "reduceOnly": false,
      "side": "A",
      "sz": "5.0",
      "timestamp": 1681247412573,
      "triggerCondition": "N/A",
      "triggerPx": "0.0"
    }
  ]
}

POST/api/upgrade/v2/hl/info

Get User Fees

Get the user's fee rate information.

Request Body Parameters

Name
user
Type
string
Description
User wallet address.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
User fee information.

Request

POST

/api/upgrade/v2/hl/info

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/info?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"type":"userFees","user": "0x0000000000000000000000000000000000000000"}'

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "dailyUserVlm": "1000000.00",
    "feeSchedule": {
      "taker": "0.00035",
      "maker": "0.0001"
    }
  }
}

POST/api/upgrade/v2/hl/info

Get User Fills (Info API)

Get the user's fill list.

Request Body Parameters

Name
user
Type
string
Description
User wallet address.
Name
aggregateByTime
Type
boolean
Description
Optional. Whether to aggregate by time.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Fill list.

Request

POST

/api/upgrade/v2/hl/info

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/info?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"type":"userFills","user": "0x0000000000000000000000000000000000000000"}'

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "closedPnl": "0.0",
      "coin": "ETH",
      "crossed": false,
      "dir": "Open Long",
      "hash": "0xa166e3fa...",
      "oid": 90542681,
      "px": "2400.00",
      "side": "B",
      "sz": "10.0",
      "time": 1681222254710,
      "fee": "0.84",
      "feeToken": "USDC"
    }
  ]
}

POST/api/upgrade/v2/hl/info

Get User Fills By Time Range

Get the user's fills within a given time range.

Notes:

The upstream data source currently supports querying historical fills starting from early November 2025.

Each call returns up to 2,000 records. To fetch all history, call this endpoint multiple times with different time ranges (pagination by time window).

Request Body Parameters

Name
user
Type
string
Description
User wallet address.
Name
startTime
Type
integer
Description
Start time (milliseconds timestamp).
Name
endTime
Type
integer
Description
Optional. End time (milliseconds timestamp). Defaults to the current time.
Name
aggregateByTime
Type
boolean
Description
Optional. Whether to aggregate by time.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Fill list.

Request

POST

/api/upgrade/v2/hl/info

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/info?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"type":"userFillsByTime","user": "0x0000000000000000000000000000000000000000", "startTime": 1681222254710}'

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "closedPnl": "0.0",
      "coin": "ETH",
      "dir": "Open Long",
      "oid": 90542681,
      "px": "2400.00",
      "side": "B",
      "sz": "10.0",
      "time": 1681222254710,
      "fee": "0.84",
      "feeToken": "USDC"
    }
  ]
}

POST/api/upgrade/v2/hl/info

Get Candlestick Data

Get candlestick (kline) data for a given coin.

Data coverage: The official Hyperliquid API provides only the most recent 5,000 candles per interval. The BBX Open API supports paginating to fetch a longer history. For each interval, the current coverage can reach back to 2025-11-01 up to the present.

Request Body Parameters

Name
coin
Type
string
Description
Coin symbol/name, e.g. BTC, ETH.
Name
interval
Type
string
Description
Candle interval. Supported values:
Second intervals: 1s, 3s, 5s, 10s, 15s, 30s
Minute intervals: 1m, 3m, 5m, 10m, 15m, 30m
Hour intervals: 1h, 2h, 4h, 8h, 12h
Day/week/month intervals: 1d, 3d, 1w, 1M
Name
startTime
Type
integer
Description
Start time (milliseconds timestamp). The earliest available historical data is 2025-11-01.
Name
endTime
Type
integer
Description
Optional. End time (milliseconds timestamp).

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Candlestick data array.

Request

POST

/api/upgrade/v2/hl/info

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/info?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"type":"candleSnapshot","req":{"coin": "BTC", "interval": "15m", "startTime": 1681923600000, "endTime": 1681924499999}}'

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "T": 1681924499999,
      "c": "29258.0",
      "h": "29309.0",
      "i": "15m",
      "l": "29250.0",
      "n": 189,
      "o": "29295.0",
      "s": "BTC",
      "t": 1681923600000,
      "v": "0.98639"
    }
  ]
}

POST/api/upgrade/v2/hl/info

Get Perp DEX List

Get the list of perpetual DEXs supported by Hyperliquid.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Perp DEX list.

Request

POST

/api/upgrade/v2/hl/info

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/info?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"type":"perpDexs"}'

Response

{
  "code": "0",
  "msg": "success",
  "data": ["", "HLP"]
}

POST/api/upgrade/v2/hl/info

Get All Mid Prices

Get mid prices for all coins.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
A mapping of coin symbol/name to mid price.

Request

POST

/api/upgrade/v2/hl/info

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/info?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"type":"allMids"}'

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "BTC": "87927.5",
    "ETH": "2936.55",
    "SOL": "122.975"
  }
}

POST/api/upgrade/v2/hl/info

Get L2 Order Book

Get the L2 order book for a given coin.

Request Body Parameters

Name
coin
Type
string
Description
Coin symbol/name, e.g. BTC, ETH.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
L2 order book payload.

Request

POST

/api/upgrade/v2/hl/info

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/info?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"type":"l2Book","coin":"BTC"}'

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "coin": "BTC",
    "levels": [
      [
        {"n": 6, "px": "87927", "sz": "0.51696"},
        {"n": 5, "px": "87926", "sz": "0.05574"}
      ],
      [
        {"n": 39, "px": "87928", "sz": "11.96592"},
        {"n": 1, "px": "87929", "sz": "0.00012"}
      ]
    ],
    "time": 1769684718911
  }
}

POST/api/upgrade/v2/hl/info

Get Historical Orders

Get the user's historical orders. Returns up to the 2,000 most recent orders.

Request Body Parameters

Name
user
Type
string
Description
User wallet address.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Historical order list.

Request

POST

/api/upgrade/v2/hl/info

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/info?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"type":"historicalOrders","user": "0x0000000000000000000000000000000000000000"}'

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "order": {
        "coin": "ETH",
        "side": "A",
        "limitPx": "2412.7",
        "sz": "0.0",
        "oid": 1,
        "timestamp": 1724361546645,
        "triggerCondition": "N/A",
        "isTrigger": false,
        "orderType": "Market",
        "origSz": "0.0076"
      },
      "status": "filled",
      "statusTimestamp": 1724361546645
    }
  ]
}

POST/api/upgrade/v2/hl/info

Get Order Status

Query the status of a specific order.

Request Body Parameters

Name
user
Type
string
Description
User wallet address.
Name
oid
Type
string|integer
Description
Order ID. Can be a number or a hex string.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
Order status payload.

Request

POST

/api/upgrade/v2/hl/info

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/info?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"type":"orderStatus","user": "0x0000000000000000000000000000000000000000", "oid": 91490942}'

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "order": {
      "coin": "BTC",
      "limitPx": "29792.0",
      "oid": 91490942,
      "side": "A",
      "sz": "5.0",
      "timestamp": 1681247412573
    },
    "status": "open",
    "statusTimestamp": 1681247412573
  }
}

POST/api/upgrade/v2/hl/info

Get User Funding History

Get the user's funding history.

Request Body Parameters

Name
user
Type
string
Description
User wallet address.
Name
startTime
Type
integer
Description
Start time (milliseconds timestamp).
Name
endTime
Type
integer
Description
Optional. End time (milliseconds timestamp). Defaults to the current time.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Funding history list.

Request

POST

/api/upgrade/v2/hl/info

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/info?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"type":"userFunding","user": "0x0000000000000000000000000000000000000000", "startTime": 1681222254710}'

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "delta": {
        "coin": "ETH",
        "fundingRate": "0.0000417",
        "szi": "49.1477",
        "type": "funding",
        "usdc": "-3.625312"
      },
      "hash": "0xa166e3fa...",
      "time": 1681222254710
    }
  ]
}

POST/api/upgrade/v2/hl/info

Get User Non-funding Ledger Updates

Get the user's non-funding ledger updates, such as deposits, transfers, and withdrawals.

Request Body Parameters

Name
user
Type
string
Description
User wallet address.
Name
startTime
Type
integer
Description
Start time (milliseconds timestamp).
Name
endTime
Type
integer
Description
Optional. End time (milliseconds timestamp). Defaults to the current time.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
Ledger update list.

Request

POST

/api/upgrade/v2/hl/info

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/info?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"type":"userNonFundingLedgerUpdates","user": "0x0000000000000000000000000000000000000000", "startTime": 1681222254710}'

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "delta": {
        "type": "deposit",
        "usdc": "1000.00"
      },
      "hash": "0xb2f7d1e3...",
      "time": 1681222254710
    },
    {
      "delta": {
        "type": "withdraw",
        "usdc": "-500.00"
      },
      "hash": "0xc3g8e2f4...",
      "time": 1681308654710
    }
  ]
}

POST/api/upgrade/v2/hl/info

Get User Portfolio

Get the user's portfolio.

Request Body Parameters

Name
user
Type
string
Description
User wallet address.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
Portfolio payload.

Request

POST

/api/upgrade/v2/hl/info

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/info?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"type":"portfolio","user":"0x0000000000000000000000000000000000000000"}'

Response

{
  "code": "0",
  "msg": "success",
  "data": {}
}

POST/api/upgrade/v2/hl/info

Get Web Aggregated Data

Get the user's web aggregated data.

Request Body Parameters

Name
user
Type
string
Description
User wallet address.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
Web aggregated data payload.

Request

POST

/api/upgrade/v2/hl/info

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/info?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"type":"webData2","user":"0x0000000000000000000000000000000000000000"}'

Response

{
  "code": "0",
  "msg": "success",
  "data": {}
}

POST/api/upgrade/v2/hl/info

Get User TWAP Slice Fills

Get the user's TWAP slice fills.

Request Body Parameters

Name
user
Type
string
Description
User wallet address.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
array
Description
TWAP slice fill list.

Request

POST

/api/upgrade/v2/hl/info

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/info?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"type":"userTwapSliceFills","user":"0x0000000000000000000000000000000000000000"}'

Response

{
  "code": "0",
  "msg": "success",
  "data": []
}

POST/api/upgrade/v2/hl/info

Get Active Asset Data

Get active asset data for a given user and coin.

Request Body Parameters

Name
user
Type
string
Description
User wallet address.
Name
coin
Type
string
Description
Coin symbol/name, e.g. BTC, ETH.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
Active asset data payload.

Request

POST

/api/upgrade/v2/hl/info

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/info?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"type":"activeAssetData","user":"0x0000000000000000000000000000000000000000","coin":"BTC"}'

Response

{
  "code": "0",
  "msg": "success",
  "data": {}
}

GET/api/upgrade/v2/hl/traders/:address/detailed-trading-statistics

Get Detailed Trading Statistics and Win Rate

Get detailed trading statistics for the given address over the selected period, including win rate, PnL, holding duration, best trades, and per-asset performance.

Path Parameters

Name
address
Type
string
Description
User wallet address, e.g. 0xfe00xxx

Query Parameters

Name
period
Type
integer
Description
Period length in days. Supported values: 7, 30, 0 (0 means all-time). Default 30.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
Detailed trading statistics payload, including fields such as totalPnl, winRate, bestTrades, and performanceAssets.

Request

GET

/api/upgrade/v2/hl/traders/:address/detailed-trading-statistics

curl -G "https://open.bbx.com/api/upgrade/v2/hl/traders/0xfe00xxx/detailed-trading-statistics?period=30" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "code": "0",
  "msg": "success",
  "data": {
    "totalPnl": "244007.22",
    "gross": "310998.74",
    "fees": "66991.52",
    "longPnl": "129040.34",
    "shortPnl": "114966.88",
    "winRate": "0.6093",
    "winning": 138352,
    "total": 227050,
    "tradeDuration": 69452112,
    "minDuration": 0,
    "maxDuration": 204948,
    "bestTrades": [
      {
        "coin": "xyz:CL",
        "direction": "long",
        "duration": 140432,
        "createAt": 1776209853140,
        "pnl": "3868.78"
      }
    ],
    "performanceAssets": [
      {
        "trades": 17465,
        "coin": "xyz:CL",
        "pnl": "41586.20",
        "fees": "284.59"
      }
    ]
  }
}

POST/api/upgrade/v2/hl/traders/query-addr-tags

Batch Query Address Tags

Batch query trader tags for multiple addresses (capital size, directional bias, holding style, etc.). Supports both English and Chinese. Tags are updated daily.

Request Parameters

Name
addresses
Type
array
Description
Address list. Up to 2,000 addresses.
Name
lang
Type
string
Description
Language: en (English, default) or zh (Chinese).

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
Address tag list. Each item contains address and a tags array.

Tag Dimensions

Dimension	English	Chinese
Capital	Shrimp / Shark / Whale	小资金 / 中等资金 / 巨鲸
Direction	Bearish / Neutral / Bullish	偏空头 / 中性 / 偏多头
Term	Scalper / Short-term / Swinger / Long-term	超短线 / 短线 / 波段 / 长线
Gain	Small / Mid / Large Gain	小额 / 中等 / 大额盈利
Profitability	Sustained / Volatile Profit / Breakeven	持续 / 波动盈利 / 盈亏平衡
Style	Aggr. Hi-Freq / Cons. Low-Freq / Low DD / ...	高频激进 / 低频稳健 / 低回撤 / ...

Request

POST

/api/upgrade/v2/hl/traders/query-addr-tags

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/traders/query-addr-tags?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": ["0x020cxxx", "0x265cxxx"],
    "lang": "en"
  }'

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "address": "0x020cxxx",
      "tags": ["Whale", "Bullish", "Swinger", "Small Gain"]
    },
    {
      "address": "0x265cxxx",
      "tags": ["Shrimp", "Neutral", "Short-term", "Breakeven", "Low DD"]
    }
  ]
}

POST/api/upgrade/v2/hl/ledger-updates/deposits-withdrawals

Query Deposit and Withdrawal Records

Batch query deposit and withdrawal records for multiple addresses. Supports filtering by time range and returns results in reverse chronological order.

Request Parameters

Name
addresses
Type
array
Description
Address list. Up to 2,000 addresses.
Name
startTime
Type
integer
Description
Optional. Start time (milliseconds timestamp).
Name
endTime
Type
integer
Description
Optional. End time (milliseconds timestamp).
Name
limit
Type
integer
Description
Optional. Max number of records to return. Default 10000, max 50000.

Request Parameters

Name
AccessKeyId
Type
string
Description
User access key ID.
Name
SignatureNonce
Type
string
Description
Signature nonce.
Name
Timestamp
Type
string
Description
Request timestamp (seconds), valid for 30 seconds.
Name
Signature
Type
string
Description
Signature generated with HmacSHA1 + Base64. See How to generate API auth parameters.

Response

Name
code
Type
string
Description
Status code. "0" means success.
Name
msg
Type
string
Description
Response message.
Name
data
Type
object
Description
Deposit/withdrawal record list. Each item includes fields like address, time, type, hash, usdc, etc.

Request

POST

/api/upgrade/v2/hl/ledger-updates/deposits-withdrawals

curl -X POST "https://open.bbx.com/api/upgrade/v2/hl/ledger-updates/deposits-withdrawals?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": ["0x020cxxx"],
    "startTime": 1730419200000,
    "limit": 100
  }'

Response

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "address": "0x020cxxx",
      "time": 1775162591423,
      "type": "deposit",
      "hash": "0xc6d884xxx",
      "token": null,
      "usdc": 20000,
      "amount": null,
      "fee": null,
      "netWithdrawnUsd": null,
      "requestedUsd": null
    },
    {
      "address": "0x020cxxx",
      "time": 1774000000000,
      "type": "withdraw",
      "hash": "0xa1b2c3xxx",
      "token": null,
      "usdc": -5000,
      "amount": null,
      "fee": 1,
      "netWithdrawnUsd": null,
      "requestedUsd": null
    }
  ]
}

Error Codes

Error Code	Description
0	Success
400	Invalid request parameters.
401	Unauthorized. API key is missing or invalid.
403	Forbidden.
500	Internal server error.

Hyperliquid API

Authentication

Heartbeat

Connection Example

Supported Subscription Types (subscription.type)

candle Subscription

Subscription Example

Subscribe and Unsubscribe

Address Subscription

View Connection Stats

Close Connection

Push Message Example

Connection

Subscribe and Unsubscribe

Push Message Example

Connection

Query Parameters

Subscribe and Unsubscribe

Address Subscription Example

Push Message Example

Connection

Request Parameters

Response

Request

Response

Path Parameters

Request Parameters

Response

Request

Response

Path Parameters

Query Parameters

Request Parameters

Response

Request

Response

Path Parameters

Request Parameters

Response

Request

Response

Path Parameters

Request Parameters

Response

Request

Response

Path Parameters

Query Parameters

Request Parameters

Response

Request

Response

Query Parameters

Request Parameters

Response

Request

Response

Path Parameters

Query Parameters

Request Parameters

Response

Request

Response

Path Parameters

Request Parameters

Response

Request

Response

Path Parameters

Query Parameters

Request Parameters

Response

Request

Response

Path Parameters

Request Parameters

Response

Request

Response

Query Parameters

Supported Subscription Types (`subscription.type`)

`candle` Subscription