BBX Open API Docs
中文English

Distributor Management API

The Distributor API lets partners manage API keys and issue sub keys to their customers, enabling independent user management and quota control.

Basics

  • Base URL: https://open.bbx.com/api/upgrade/v2/distributor
  • Authentication: Signature parameters (see Generate API Signature)

Notes:

  • Signature parameters (AccessKeyId / SignatureNonce / Timestamp / Signature) must be placed in the URL query string. The signature is calculated from the following string only (fixed order): AccessKeyId={AccessKeyId}&SignatureNonce={SignatureNonce}&Timestamp={Timestamp}. Then use SecretKey to compute HmacSHA1 and take the hex digest, and finally Base64-encode the hex string.
  • Business parameters go in the JSON request body (for POST/PUT endpoints only).
  • For GET requests, all business parameters go in the URL query string.

Required Parameters

Every request to the management API must include:

  • AccessKeyId
  • SignatureNonce
  • Timestamp
  • Signature
POST/api/upgrade/v2/distributor/register

Distributor Self-Registration (Invite Token)

Use the invite token provided by an admin to self-register as a distributor and obtain your dedicated AccessKey and SecretKey.

This endpoint is public and does not require signature authentication.

Invite Token Rules

  • The invite token is generated by an admin in advance and includes preset distributor configuration (name, level, sub key limit, monthly total quota, WS connection/subscription limits, etc.).
  • One-time use: the invite token becomes invalid immediately after successful registration and cannot be reused.
  • Using an invalid or already-consumed invite token returns a 400 error.
  • After registration, the distributor must configure levels for sub keys via Create or Update Level Config to set permissions (permissions) and quota templates (request_limits). A sub key with no level permissions cannot access any data endpoints (403).

Request Parameters

  • Name
    invite_token
    Type
    string
    Description
    Invite token provided by the admin (required)

Response

  • Name
    success
    Type
    boolean
    Description
    Request status
  • Name
    data
    Type
    object
    Description

    Response data

    • Name
      access_key
      Type
      string
      Description
      Distributor AccessKey
    • Name
      secret_key
      Type
      string
      Description
      Distributor SecretKey (shown only once; store it securely)
    • Name
      name
      Type
      string
      Description
      Distributor name (preset by the invite token)
    • Name
      level
      Type
      string
      Description
      Distributor level (preset by the invite token)
  • Name
    message
    Type
    string
    Description
    Result message

Important: secret_key is returned only once upon successful registration and cannot be retrieved again. Save it securely immediately after receiving the response.

Request

POST
/api/upgrade/v2/distributor/register
curl -X POST https://open.bbx.com/api/upgrade/v2/distributor/register \
  -H 'Content-Type: application/json' \
  -d '{
    "invite_token": "your_invite_token_here"
  }'

Response (Success)

{
  "success": true,
  "data": {
    "access_key": "dist_ak_xxxx",
    "secret_key": "dist_sk_xxxx",
    "name": "Partner-Alpha",
    "level": "standard"
  },
  "message": "Distributor registration completed successfully. Store the SecretKey securely because it is shown only once."
}

Response (Invalid or Used Invite Token)

{
  "success": false,
  "error": "The invite token is invalid or has already expired."
}
GET/api/upgrade/v2/distributor/info

Get Distributor Info

Get the current distributor's basic information (including the sub key limit and monthly total quota).

Request Parameters

  • Name
    AccessKeyId
    Type
    string
    Description
    Distributor primary AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    Signature nonce
  • Name
    Timestamp
    Type
    string
    Description
    Request timestamp (seconds)
  • Name
    Signature
    Type
    string
    Description
    Signature generated with HmacSHA1 + Base64

Response

  • Name
    success
    Type
    boolean
    Description
    Request status
  • Name
    data
    Type
    object
    Description

    Response data

    • Name
      access_key
      Type
      string
      Description
      Distributor AccessKey
    • Name
      name
      Type
      string
      Description
      Distributor name
    • Name
      level
      Type
      string
      Description
      Distributor level
    • Name
      max_sub_keys
      Type
      integer
      Description
      Maximum number of sub keys allowed
    • Name
      sub_key_count
      Type
      integer
      Description
      Current number of sub keys
    • Name
      max_total_quota
      Type
      integer
      Description
      Distributor monthly total quota limit

Request

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

Response

{
  "success": true,
  "data": {
    "access_key": "distributor_ak_xxxx",
    "name": "Partner-Alpha",
    "level": "Default",
    "max_sub_keys": 100,
    "sub_key_count": 45,
    "max_total_quota": 1000000
  }
}
GET/api/upgrade/v2/distributor/quota

Get Quota Details

Get monthly quota reconciliation details at the distributor level (allocated/available/used/remaining).

Request Parameters

  • Name
    AccessKeyId
    Type
    string
    Description
    Distributor primary AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    Signature nonce
  • Name
    Timestamp
    Type
    string
    Description
    Request timestamp (seconds)
  • Name
    Signature
    Type
    string
    Description
    Signature generated with HmacSHA1 + Base64

Notes:

  • max_total_quota is the distributor-level hard cap for total monthly requests (sum of consumption across all sub keys).
  • allocated_quota is the sum of monthly quotas currently allocated to all sub keys.
  • available_quota is the remaining monthly quota that can still be allocated to sub keys (max_total_quota - allocated_quota).
  • used_quota is the cumulative number of requests used by all sub keys in the current month.
  • remaining_quota is the remaining usable requests under the distributor's total monthly quota (max(max_total_quota - used_quota, 0)).

Response

  • Name
    success
    Type
    boolean
    Description
    Request status
  • Name
    data
    Type
    object
    Description

    Response data

    • Name
      max_total_quota
      Type
      integer
      Description
      Contracted maximum total monthly request quota
    • Name
      allocated_quota
      Type
      integer
      Description
      Total monthly quota allocated to all sub keys
    • Name
      available_quota
      Type
      integer
      Description
      Remaining quota available to allocate
    • Name
      used_quota
      Type
      integer
      Description
      Requests used this month (sum across all sub keys)
    • Name
      remaining_quota
      Type
      integer
      Description
      Remaining usable requests this month

Request

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

Response

{
  "success": true,
  "data": {
    "max_total_quota": 1000000,
    "allocated_quota": 650000,
    "available_quota": 350000,
    "used_quota": 12500,
    "remaining_quota": 987500
  }
}
GET/api/upgrade/v2/distributor/levels

List Available Levels

List the level names that have been configured for the current distributor.

Request Parameters

  • Name
    AccessKeyId
    Type
    string
    Description
    Distributor primary AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    Signature nonce
  • Name
    Timestamp
    Type
    string
    Description
    Request timestamp (seconds)
  • Name
    Signature
    Type
    string
    Description
    Signature generated with HmacSHA1 + Base64

Response

  • Name
    success
    Type
    boolean
    Description
    Request status
  • Name
    data
    Type
    array
    Description
    List of level names

Request

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

Response

{
  "success": true,
  "data": ["gold", "silver"]
}
GET/api/upgrade/v2/distributor/levels/:level

Get Level Config

Returns the quota template and permission set for the specified level.

Request Parameters

  • Name
    level
    Type
    string
    Description
    Level name (path parameter)
  • Name
    AccessKeyId
    Type
    string
    Description
    Distributor primary AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    Signature nonce
  • Name
    Timestamp
    Type
    string
    Description
    Request timestamp (seconds)
  • Name
    Signature
    Type
    string
    Description
    Signature generated with HmacSHA1 + Base64

Response

  • Name
    success
    Type
    boolean
    Description
    Request status
  • Name
    data
    Type
    object
    Description

    Response data

    • Name
      request_limits
      Type
      object
      Description

      Quota template

      • Name
        max_time_range
        Type
        integer
        Description
        Maximum query time range (seconds)
      • Name
        max_request
        Type
        integer
        Description
        Default monthly request quota
      • Name
        request_rate_limit
        Type
        integer
        Description
        Requests per minute rate limit (QPM)
    • Name
      permissions
      Type
      array
      Description
      Permission set (resource_type + actions)

Request

GET
/api/upgrade/v2/distributor/levels/:level
curl -G https://open.bbx.com/api/upgrade/v2/distributor/levels/gold \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "success": true,
  "data": {
    "request_limits": {
      "max_time_range": 2592000,
      "max_request": 200000,
      "request_rate_limit": 120
    },
    "permissions": [
      {"resource_type": "hyperliquid", "actions": ["HL_TICKERS", "HL_FILLS", "HL_INFO"]}
    ]
  }
}
PUT/api/upgrade/v2/distributor/levels/:level

Create or Update Level Config

Create or update the "quota template + permission set" for the specified level.

Request Parameters

  • Name
    level
    Type
    string
    Description
    Level name (path parameter)
  • Name
    request_limits
    Type
    object
    Description
    Quota template
  • Name
    permissions
    Type
    array
    Description
    Permission set (resource_type + actions)
  • Name
    AccessKeyId
    Type
    string
    Description
    Distributor primary AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    Signature nonce
  • Name
    Timestamp
    Type
    string
    Description
    Request timestamp (seconds)
  • Name
    Signature
    Type
    string
    Description
    Signature generated with HmacSHA1 + Base64

Notes:

  • permissions defines which endpoints this level is allowed to call.
  • request_limits defines the quota template for this level.

permissions Field Structure

permissions is an array. Each item contains:

  • resource_type (string): must be "hyperliquid". Distributors can only configure permissions for the Hyperliquid module. Passing other values (for example futures or trading_pair) returns HTTP 400.
  • actions (string[]): list of actions allowed under that resource type. See "Available Actions" below.

Because resource_type is fixed to hyperliquid, in practice you only need to manage actions.

request_limits Fields

FieldTypeDescription
max_time_rangeintegerMaximum query time range (seconds)
max_requestintegerDefault monthly request quota
request_rate_limitintegerRequests-per-minute rate limit (QPM)

How Permissions Map to Endpoints

Each API endpoint is registered on the server with a (resource_type, action) pair. When a sub key makes a request, the system checks whether the sub key's level permissions contains the endpoint's action. If yes, the request is allowed. If not, the request is rejected with HTTP 403.

Put simply: one endpoint maps to one action, and the level's permissions determines which endpoints sub keys can call.

Important: New Endpoints Require Level Updates

When the platform ships new API endpoints, corresponding Actions are added. Existing level configs do not automatically include new Actions. Distributors must call this endpoint (PUT /api/upgrade/v2/distributor/levels/:level) to add the new Actions into permissions before sub keys can access the new endpoints.

We recommend updating your level permission configs as soon as you receive a notification about new endpoints.

Available Actions

The tables below map each Action to its corresponding endpoint(s):

Data Queries

ActionEndpoints
HL_TICKERSGET /hl/tickers, GET /hl/tickers/coin/:coin
HL_FILLSGET /hl/fills/:address, GET /hl/fills/oid/:oid
HL_FILLS_BY_TWAP_IDGET /hl/fills/twapid/:twapid
HL_FILLS_BUILDERGET /hl/fills/builder/:builder/latest
HL_FILLED_ORDERSGET /hl/filled-orders/:address/latest, GET /hl/filled-orders/oid/:oid
HL_ORDERSGET /hl/orders/:address/latest, GET /hl/orders/oid/:oid
HL_PORTFOLIOGET /hl/portfolio/:address/:window
HL_PNLSGET /hl/pnls/:address
HL_BATCH_PNLSPOST /hl/batch-pnls
HL_BEST_TRADESGET /hl/traders/:address/best-trades
HL_PERFORMANCE_BY_COINGET /hl/traders/:address/performance-by-coin
HL_ADDR_STATGET /hl/traders/:address/addr-stat
HL_COMPLETED_TRADESGET /hl/traders/:address/completed-trades
HL_OPEN_INTEREST_SUMMARYGET /hl/open-interest/summary
HL_OPEN_INTEREST_TOP_COINSGET /hl/open-interest/top-coins
HL_ACCUMULATED_TAKER_DELTAGET /hl/accumulated-taker-delta/:coin
HL_ORDERBOOKS_HISTORY_SUMMARIESGET /hl/orderbooks/history-summaries/:coin
HL_OPEN_INTEREST_HISTORYGET /hl/open-interest/history/:coin
HL_KLINES_WITH_TAKER_VOLGET /hl/klines-with-taker-vol/:coin/:interval
HL_TOP_TRADESGET /hl/fills/top-trades
HL_TOP_OPEN_ORDERSGET /hl/orders/top-open-orders
HL_ACTIVE_STATSGET /hl/orders/active-stats
HL_CURRENT_POSITION_HISTORYGET /hl/traders/:address/current-position-history/:coin
HL_COMPLETED_POSITION_HISTORYGET /hl/traders/:address/completed-position-history/:coin
HL_CURRENT_POSITION_PNLGET /hl/traders/:address/current-position-pnl/:coin
HL_COMPLETED_POSITION_PNLGET /hl/traders/:address/completed-position-pnl/:coin
HL_CURRENT_POSITION_EXECUTIONSGET /hl/traders/:address/current-position-executions/:coin
HL_COMPLETED_POSITION_EXECUTIONSGET /hl/traders/:address/completed-position-executions/:coin
HL_MAX_DRAWDOWNGET /hl/max-drawdown/:address
HL_BATCH_MAX_DRAWDOWNPOST /hl/batch-max-drawdown
HL_LEDGER_UPDATES_NET_FLOWGET /hl/ledger-updates/net-flow/:address
HL_BATCH_LEDGER_UPDATES_NET_FLOWPOST /hl/ledger-updates/batch-net-flow
HL_COMPLETED_TRADES_BY_TIMEPOST /hl/traders/:address/completed-trades/by-time

Smart Money / Whales

ActionEndpoints
HL_TRADERS_ACCOUNTSPOST /hl/traders/accounts
HL_TRADERS_STATISTICSPOST /hl/traders/statistics
HL_SMART_FINDPOST /hl/smart/find
HL_TRADERS_DISCOVERPOST /hl/traders/discover
HL_TRADERS_DISCOVER_HISTORYPOST /hl/traders/discover-history
HL_WHALES_OPEN_POSITIONSGET /hl/whales/open-positions
HL_WHALES_LATEST_EVENTSGET /hl/whales/latest-events
HL_WHALES_DIRECTIONSGET /hl/whales/directions
HL_WHALES_HISTORY_LONG_RATIOGET /hl/whales/history-long-ratio

Liquidations / TWAP

ActionEndpoints
HL_LIQUIDATIONS_STATGET /hl/liquidations/stat
HL_LIQUIDATIONS_STAT_BY_COINGET /hl/liquidations/stat-by-coin
HL_LIQUIDATIONS_HISTORYGET /hl/liquidations/history
HL_LIQUIDATIONS_TOP_POSITIONSGET /hl/liquidations/top-positions
HL_TWAP_STATESGET /hl/twap-states/:address/latest
HL_BATCH_ADDR_STATPOST /hl/traders/batch-addr-stat (batch query address trading stats)
HL_WS_CLEARINGHOUSE_STATEGET /hl/ws/clearinghouse-state (WebSocket subscription: account state)

Info API Proxy

ActionEndpoints
HL_INFOPOST /hl/info (unified endpoint routed by the request body type field)
HL_INFO_BATCH_CLEARINGHOUSE_STATEPOST /hl/traders/clearinghouse-state (batch query perpetual account state)
HL_INFO_BATCH_SPOT_CLEARINGHOUSE_STATEPOST /hl/traders/spot-clearinghouse-state (batch query spot account state)

Note: HL_INFO is the single permission gate for the unified POST /hl/info endpoint. With HL_INFO, you can access all subtypes under that endpoint (including meta, spotMeta, clearinghouseState, webData2, userFills, etc.). Fine-grained authorization by type is not currently supported. The HL_INFO_* Actions below are reserved for future expansion; configuring them has no additional effect today.

HL_INFO Granular Permissions (Reserved)

ActionDescription
HL_INFO_METAMetadata query
HL_INFO_SPOT_METASpot metadata query
HL_INFO_CLEARINGHOUSE_STATESingle-address perpetual account state
HL_INFO_SPOT_CLEARINGHOUSE_STATESingle-address spot account state
HL_INFO_OPEN_ORDERSCurrent open orders
HL_INFO_FRONTEND_OPEN_ORDERSFrontend open orders
HL_INFO_USER_FEESUser fee rates
HL_INFO_USER_FILLSUser fills
HL_INFO_USER_FILLS_BY_TIMEUser fills by time
HL_INFO_CANDLE_SNAPSHOTCandle snapshot
HL_INFO_PERP_DEXSPerpetual DEX list
HL_INFO_ACTIVE_ASSET_DATAActive asset data
HL_INFO_WEB_DATA2Web data
HL_INFO_HISTORICAL_ORDERSHistorical orders
HL_INFO_USER_TWAP_SLICE_FILLSTWAP slice fills
HL_INFO_ORDER_STATUSOrder status
HL_INFO_USER_FUNDINGUser funding rates
HL_INFO_USER_NON_FUNDING_LEDGER_UPDATESNon-funding ledger updates

WebSocket

ActionEndpoints
HL_WS_NODEGET /hl/ws
HL_WS_FILLSGET /hl/ws/fills
HL_WS_FILLED_ORDERSGET /hl/ws/filled-orders

Note: WebSocket connections are subject to additional concurrency limits. See WebSocket Connection Limits.

Response

  • Name
    success
    Type
    boolean
    Description
    Request status
  • Name
    message
    Type
    string
    Description
    Result message

Request

PUT
/api/upgrade/v2/distributor/levels/:level
curl -X PUT 'https://open.bbx.com/api/upgrade/v2/distributor/levels/gold?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE' \
  -H 'Content-Type: application/json' \
  -d '{
    "request_limits": {
      "max_time_range": 2592000,
      "max_request": 200000,
      "request_rate_limit": 120
    },
    "permissions": [
      {
        "resource_type": "hyperliquid",
        "actions": [
          "HL_TICKERS",
          "HL_FILLS",
          "HL_ORDERS",
          "HL_INFO",
          "HL_WS_NODE",
          "HL_WS_FILLS",
          "HL_WS_FILLED_ORDERS"
        ]
      }
    ]
  }'

Response

{
  "success": true,
  "message": "Operation successful"
}
DELETE/api/upgrade/v2/distributor/levels/:level

Delete Level Config

Delete the configuration for the specified level (permission set and quota template).

Request Parameters

  • Name
    level
    Type
    string
    Description
    Level name (path parameter)
  • Name
    AccessKeyId
    Type
    string
    Description
    Distributor primary AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    Signature nonce
  • Name
    Timestamp
    Type
    string
    Description
    Request timestamp (seconds)
  • Name
    Signature
    Type
    string
    Description
    Signature generated with HmacSHA1 + Base64

Response

  • Name
    success
    Type
    boolean
    Description
    Request status
  • Name
    message
    Type
    string
    Description
    Result message

Request

DELETE
/api/upgrade/v2/distributor/levels/:level
curl -X DELETE 'https://open.bbx.com/api/upgrade/v2/distributor/levels/gold?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE'

Response

{
  "success": true,
  "message": "Operation successful"
}
POST/api/upgrade/v2/distributor/sub-keys

Create Sub Key

Create a sub key and assign its own quota and rate-limiting settings.

Level Rules

When creating a sub key, you can pass the level field to determine which level configuration this sub key should use, including its permission set and quota template.

  • If level is omitted or passed as an empty string, the sub key inherits the distributor's own level.
  • If level is provided, the sub key uses the specified level. It is recommended to configure that level first through the "Create or Update Level Configuration" endpoint.

Request Parameters

  • Name
    name
    Type
    string
    Description
    Sub key name
  • Name
    level
    Type
    string
    Description
    Level name (optional; if omitted, the distributor's own level is inherited)
  • Name
    monthly_quota
    Type
    integer
    Description
    Monthly quota for the sub key (optional; if omitted, the default or automatic allocation is used; when explicitly provided it must be >= 1)
  • Name
    rate_limit
    Type
    integer
    Description
    Per-minute request limit (QPM)
  • Name
    max_time_range
    Type
    integer
    Description
    Maximum query time span in seconds
  • Name
    ws_conn_limit
    Type
    integer
    Description
    Maximum concurrent WebSocket connections (optional; omit or pass 0 for unlimited)
  • Name
    ws_sub_limit
    Type
    integer
    Description
    Maximum WebSocket subscriptions (optional; omit or pass 0 for unlimited)
  • Name
    expires_in
    Type
    integer
    Description
    Validity period in seconds
  • Name
    metadata
    Type
    string
    Description
    Additional metadata (JSON string)
  • Name
    AccessKeyId
    Type
    string
    Description
    Distributor primary AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    Request nonce
  • Name
    Timestamp
    Type
    string
    Description
    Request timestamp in seconds
  • Name
    Signature
    Type
    string
    Description
    Signature generated with HmacSHA1 + Base64

Notes:

  • secret_key is returned only once at creation time. If it is lost, use the "Reset Secret" endpoint.
  • monthly_quota:
    • When explicitly provided, it must be >= 1, otherwise the server returns 400 with the error monthly quota for sub key must be >= 1.
    • When omitted:
      • If the distributor has configured max_total_quota > 0, the default allocation is the current available quota (available_quota = max_total_quota - allocated_quota).
      • If max_total_quota == 0, the system default is used (currently 1000).
  • Actual sub key consumption is limited not only by its own monthly_quota, but also by the distributor's hard upper bound max_total_quota.
  • ws_conn_limit (optional): maximum concurrent WebSocket connections allowed for this sub key. Omit it or pass 0 for unlimited. See WebSocket Connection Limits.
  • ws_sub_limit (optional): maximum WebSocket subscriptions allowed for this sub key across a single connection's total subscribe count. Omit it or pass 0 for unlimited. See WebSocket Subscription Limits.

Response Data

  • Name
    success
    Type
    boolean
    Description
    Request status
  • Name
    data
    Type
    object
    Description

    Response payload

    • Name
      access_key
      Type
      string
      Description
      Sub AccessKey
    • Name
      secret_key
      Type
      string
      Description
      Sub SecretKey (returned only at creation time)
    • Name
      name
      Type
      string
      Description
      Sub key name
    • Name
      level
      Type
      string
      Description
      Sub key level
    • Name
      created_at
      Type
      string
      Description
      Creation time (RFC3339)
    • Name
      expires_at
      Type
      string
      Description
      Expiration time (RFC3339, may be null)
  • Name
    message
    Type
    string
    Description
    Operation result message

Request

POST
/api/upgrade/v2/distributor/sub-keys
curl -X POST 'https://open.bbx.com/api/upgrade/v2/distributor/sub-keys?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Customer A API Key",
    "level": "gold",
    "monthly_quota": 10000,
    "rate_limit": 60,
    "max_time_range": 2592000,
    "ws_conn_limit": 5,
    "ws_sub_limit": 20,
    "expires_in": 31536000,
    "metadata": "{\"customer_id\":\"12345\"}"
  }'

Response

{
  "success": true,
  "data": {
    "access_key": "sub_ak_xxxx",
    "secret_key": "sub_sk_xxxx",
    "name": "Customer A API Key",
    "level": "gold",
    "created_at": "2026-01-29T14:30:15+08:00",
    "expires_at": null
  },
  "message": "Sub key created successfully. Store the SecretKey securely."
}

Sub Key Status Codes

The status field on a sub key can have the following values:

statusMeaning
1Enabled (Active)
0Disabled

Notes:

  • A newly created sub key defaults to status=1.
  • When status=0 (disabled), all requests made with that sub key are rejected, typically with HTTP 403.
GET/api/upgrade/v2/distributor/sub-keys

List Sub Keys

Retrieve the list of sub keys, with pagination and filtering support.

Request Parameters

  • Name
    page
    Type
    integer
    Description
    Page number
  • Name
    page_size
    Type
    integer
    Description
    Items per page
  • Name
    status
    Type
    integer
    Description
    Optional status filter
  • Name
    keyword
    Type
    string
    Description
    Optional keyword filter
  • Name
    AccessKeyId
    Type
    string
    Description
    Distributor primary AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    Request nonce
  • Name
    Timestamp
    Type
    string
    Description
    Request timestamp in seconds
  • Name
    Signature
    Type
    string
    Description
    Signature generated with HmacSHA1 + Base64

Response Data

  • Name
    success
    Type
    boolean
    Description
    Request status
  • Name
    data
    Type
    object
    Description

    Response payload

    • Name
      list
      Type
      array
      Description
      Sub key list
    • Name
      total
      Type
      integer
      Description
      Total count
    • Name
      page
      Type
      integer
      Description
      Current page number
    • Name
      page_size
      Type
      integer
      Description
      Items per page

Request

GET
/api/upgrade/v2/distributor/sub-keys
curl -G https://open.bbx.com/api/upgrade/v2/distributor/sub-keys \
  -d "page=1" \
  -d "page_size=10" \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "success": true,
  "data": {
    "list": [
      {
        "access_key": "sub_ak_xxxx",
        "name": "Customer A API Key",
        "status": 1,
        "monthly_quota": 10000,
        "rate_limit": 60,
        "max_time_range": 2592000,
        "expires_at": "2026-01-29T14:30:15+08:00"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 10
  }
}
GET/api/upgrade/v2/distributor/sub-keys/:access_key

Get Sub Key Details

Retrieve the detailed information for a specific sub key.

Request Parameters

  • Name
    access_key
    Type
    string
    Description
    Sub AccessKey (path parameter)
  • Name
    AccessKeyId
    Type
    string
    Description
    Distributor primary AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    Request nonce
  • Name
    Timestamp
    Type
    string
    Description
    Request timestamp in seconds
  • Name
    Signature
    Type
    string
    Description
    Signature generated with HmacSHA1 + Base64

Response Data

  • Name
    success
    Type
    boolean
    Description
    Request status
  • Name
    data
    Type
    object
    Description
    Sub key details

Request

GET
/api/upgrade/v2/distributor/sub-keys/:access_key
curl -G https://open.bbx.com/api/upgrade/v2/distributor/sub-keys/sub_ak_xxxx \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "success": true,
  "data": {
    "access_key": "sub_ak_xxxx",
    "name": "Customer A API Key",
    "status": 1,
    "monthly_quota": 10000,
    "rate_limit": 60,
    "max_time_range": 2592000,
    "expires_at": "2026-01-29T14:30:15+08:00",
    "metadata": "{\"customer_id\":\"12345\"}"
  }
}
PUT/api/upgrade/v2/distributor/sub-keys/:access_key

Update Sub Key

Update the configuration of a specific sub key.

Request Parameters

  • Name
    access_key
    Type
    string
    Description
    Sub AccessKey (path parameter)
  • Name
    name
    Type
    string
    Description
    Sub key name (optional)
  • Name
    status
    Type
    integer
    Description
    Status (optional, 0 = disabled, 1 = enabled)
  • Name
    monthly_quota
    Type
    integer
    Description
    Monthly quota (optional)
  • Name
    rate_limit
    Type
    integer
    Description
    QPM rate limit (optional)
  • Name
    max_time_range
    Type
    integer
    Description
    Maximum query time span in seconds (optional)
  • Name
    ws_conn_limit
    Type
    integer
    Description
    Maximum concurrent WebSocket connections (optional, 0 means unlimited)
  • Name
    ws_sub_limit
    Type
    integer
    Description
    Maximum WebSocket subscriptions (optional, 0 means unlimited)
  • Name
    expires_in
    Type
    integer
    Description
    Validity period in seconds from now; pass 0 to clear the expiration
  • Name
    metadata
    Type
    string
    Description
    Additional metadata (JSON string, optional)
  • Name
    AccessKeyId
    Type
    string
    Description
    Distributor primary AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    Request nonce
  • Name
    Timestamp
    Type
    string
    Description
    Request timestamp in seconds
  • Name
    Signature
    Type
    string
    Description
    Signature generated with HmacSHA1 + Base64

Response Data

  • Name
    success
    Type
    boolean
    Description
    Request status
  • Name
    message
    Type
    string
    Description
    Operation result message

Request

PUT
/api/upgrade/v2/distributor/sub-keys/:access_key
curl -X PUT 'https://open.bbx.com/api/upgrade/v2/distributor/sub-keys/sub_ak_xxxx?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE' \
  -H 'Content-Type: application/json' \
  -d '{"monthly_quota": 20000, "rate_limit": 120}'

Response

{
  "success": true,
  "message": "Operation successful"
}
DELETE/api/upgrade/v2/distributor/sub-keys/:access_key

Delete Sub Key

Delete a specific sub key.

Request Parameters

  • Name
    access_key
    Type
    string
    Description
    Sub AccessKey (path parameter)
  • Name
    AccessKeyId
    Type
    string
    Description
    Distributor primary AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    Request nonce
  • Name
    Timestamp
    Type
    string
    Description
    Request timestamp in seconds
  • Name
    Signature
    Type
    string
    Description
    Signature generated with HmacSHA1 + Base64

Response Data

  • Name
    success
    Type
    boolean
    Description
    Request status
  • Name
    message
    Type
    string
    Description
    Operation result message

Request

DELETE
/api/upgrade/v2/distributor/sub-keys/:access_key
curl -X DELETE 'https://open.bbx.com/api/upgrade/v2/distributor/sub-keys/sub_ak_xxxx?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE'

Response

{
  "success": true,
  "message": "Operation successful"
}
POST/api/upgrade/v2/distributor/sub-keys/:access_key/enable

Enable Sub Key

Enable a specific sub key.

Request Parameters

  • Name
    access_key
    Type
    string
    Description
    Sub AccessKey (path parameter)
  • Name
    AccessKeyId
    Type
    string
    Description
    Distributor primary AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    Request nonce
  • Name
    Timestamp
    Type
    string
    Description
    Request timestamp in seconds
  • Name
    Signature
    Type
    string
    Description
    Signature generated with HmacSHA1 + Base64

Response Data

  • Name
    success
    Type
    boolean
    Description
    Request status
  • Name
    message
    Type
    string
    Description
    Operation result message

Request

POST
/api/upgrade/v2/distributor/sub-keys/:access_key/enable
curl -X POST 'https://open.bbx.com/api/upgrade/v2/distributor/sub-keys/sub_ak_xxxx/enable?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE'

Response

{
  "success": true,
  "message": "Operation successful"
}
POST/api/upgrade/v2/distributor/sub-keys/:access_key/disable

Disable Sub Key

Disable a specific sub key.

Request Parameters

  • Name
    access_key
    Type
    string
    Description
    Sub AccessKey (path parameter)
  • Name
    AccessKeyId
    Type
    string
    Description
    Distributor primary AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    Request nonce
  • Name
    Timestamp
    Type
    string
    Description
    Request timestamp in seconds
  • Name
    Signature
    Type
    string
    Description
    Signature generated with HmacSHA1 + Base64

Response Data

  • Name
    success
    Type
    boolean
    Description
    Request status
  • Name
    message
    Type
    string
    Description
    Operation result message

Request

POST
/api/upgrade/v2/distributor/sub-keys/:access_key/disable
curl -X POST 'https://open.bbx.com/api/upgrade/v2/distributor/sub-keys/sub_ak_xxxx/disable?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE'

Response

{
  "success": true,
  "message": "Operation successful"
}
POST/api/upgrade/v2/distributor/sub-keys/:access_key/reset-secret

Reset Sub Key Secret

Reset the secret of a specific sub key. Once reset, the previous SecretKey becomes invalid immediately.

Request Parameters

  • Name
    access_key
    Type
    string
    Description
    Sub AccessKey (path parameter)
  • Name
    AccessKeyId
    Type
    string
    Description
    Distributor primary AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    Request nonce
  • Name
    Timestamp
    Type
    string
    Description
    Request timestamp in seconds
  • Name
    Signature
    Type
    string
    Description
    Signature generated with HmacSHA1 + Base64

Response Data

  • Name
    success
    Type
    boolean
    Description
    Request status
  • Name
    data
    Type
    object
    Description

    Response payload

    • Name
      access_key
      Type
      string
      Description
      Sub AccessKey
    • Name
      secret_key
      Type
      string
      Description
      New sub SecretKey
  • Name
    message
    Type
    string
    Description
    Operation result message

Request

POST
/api/upgrade/v2/distributor/sub-keys/:access_key/reset-secret
curl -X POST 'https://open.bbx.com/api/upgrade/v2/distributor/sub-keys/sub_ak_xxxx/reset-secret?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE'

Response

{
  "success": true,
  "data": {
    "access_key": "sub_ak_xxxx",
    "secret_key": "new_sub_sk_xxxx"
  },
  "message": "Sub key secret reset successfully. Store the new SecretKey securely."
}
GET/api/upgrade/v2/distributor/sub-keys/stats

Sub Key Stats

Get the total number of sub keys, enabled and disabled counts, and a monthly quota usage overview for the distributor.

Request Parameters

  • Name
    AccessKeyId
    Type
    string
    Description
    Distributor primary AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    Request nonce
  • Name
    Timestamp
    Type
    string
    Description
    Request timestamp in seconds
  • Name
    Signature
    Type
    string
    Description
    Signature generated with HmacSHA1 + Base64

Response Data

  • Name
    success
    Type
    boolean
    Description
    Request status
  • Name
    data
    Type
    object
    Description
    Statistics payload

Request

GET
/api/upgrade/v2/distributor/sub-keys/stats
curl -G https://open.bbx.com/api/upgrade/v2/distributor/sub-keys/stats \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response

{
  "success": true,
  "data": {
    "total_sub_keys": 120,
    "active_sub_keys": 115,
    "disabled_sub_keys": 5,
    "total_quota": 1000000,
    "used_quota": 450000,
    "remaining_quota": 550000
  }
}
POST/api/upgrade/v2/distributor/sub-keys/batch-enable

Batch Enable Sub Keys

Enable multiple sub keys in a single request.

Request Parameters

  • Name
    access_keys
    Type
    array
    Description
    List of sub AccessKeys to enable
  • Name
    AccessKeyId
    Type
    string
    Description
    Distributor primary AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    Request nonce
  • Name
    Timestamp
    Type
    string
    Description
    Request timestamp in seconds
  • Name
    Signature
    Type
    string
    Description
    Signature generated with HmacSHA1 + Base64

Response Data

  • Name
    success
    Type
    boolean
    Description
    Request status
  • Name
    message
    Type
    string
    Description
    Operation result message

Request

POST
/api/upgrade/v2/distributor/sub-keys/batch-enable
curl -X POST 'https://open.bbx.com/api/upgrade/v2/distributor/sub-keys/batch-enable?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE' \
  -H 'Content-Type: application/json' \
  -d '{"access_keys": ["ak_xxx1", "ak_xxx2"]}'

Response

{
  "success": true,
  "message": "Operation successful"
}
POST/api/upgrade/v2/distributor/sub-keys/batch-disable

Batch Disable Sub Keys

Disable multiple sub keys in a single request.

Request Parameters

  • Name
    access_keys
    Type
    array
    Description
    List of sub AccessKeys to disable
  • Name
    AccessKeyId
    Type
    string
    Description
    Distributor primary AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    Request nonce
  • Name
    Timestamp
    Type
    string
    Description
    Request timestamp in seconds
  • Name
    Signature
    Type
    string
    Description
    Signature generated with HmacSHA1 + Base64

Response Data

  • Name
    success
    Type
    boolean
    Description
    Request status
  • Name
    message
    Type
    string
    Description
    Operation result message

Request

POST
/api/upgrade/v2/distributor/sub-keys/batch-disable
curl -X POST 'https://open.bbx.com/api/upgrade/v2/distributor/sub-keys/batch-disable?AccessKeyId=YOUR_ACCESS_KEY_ID&SignatureNonce=RANDOM_NONCE&Timestamp=CURRENT_TIMESTAMP&Signature=YOUR_SIGNATURE' \
  -H 'Content-Type: application/json' \
  -d '{"access_keys": ["ak_xxx1", "ak_xxx2"]}'

Response

{
  "success": true,
  "message": "Operation successful"
}
GET/api/upgrade/v2/distributor/sub-keys/export

Export Sub Keys

Export sub key data and return the content as a JSON file body.

Request Parameters

  • Name
    keyword
    Type
    string
    Description
    Optional keyword filter
  • Name
    AccessKeyId
    Type
    string
    Description
    Distributor primary AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    Request nonce
  • Name
    Timestamp
    Type
    string
    Description
    Request timestamp in seconds
  • Name
    Signature
    Type
    string
    Description
    Signature generated with HmacSHA1 + Base64

Response Data

  • Name
    body
    Type
    array
    Description
    Exported sub key data list (the response body is a JSON array)

Request

GET
/api/upgrade/v2/distributor/sub-keys/export
curl -G https://open.bbx.com/api/upgrade/v2/distributor/sub-keys/export \
  -d "AccessKeyId=YOUR_ACCESS_KEY_ID" \
  -d "SignatureNonce=RANDOM_NONCE" \
  -d "Timestamp=CURRENT_TIMESTAMP" \
  -d "Signature=YOUR_SIGNATURE"

Response (file content example)

[
  {
    "access_key": "sub_ak_xxxx",
    "name": "Customer A API Key",
    "status": 1,
    "monthly_quota": 10000,
    "used_monthly_quota": 1200,
    "created_at": "2026-01-27T14:30:15+08:00"
  }
]

WebSocket Connection Limits

The WebSocket endpoints (GET /hl/ws, GET /hl/ws/fills, GET /hl/ws/filled-orders) are subject to the following connection limits:

Sub Key Connection Limit

  • When creating a sub key, you can set ws_conn_limit to define the maximum number of concurrent WebSocket connections allowed for that sub key.
  • All WS paths share the same connection counter: the combined total of /hl/ws, /hl/ws/fills, and /hl/ws/filled-orders cannot exceed ws_conn_limit.
  • When the limit is exceeded, new connection requests return HTTP 429 with the error ws connection limit exceeded for sub key.
  • After an existing connection is closed, the corresponding connection slot is automatically released within a few seconds and a new connection can then be established.

Distributor Primary Key Restriction

  • The distributor primary key is not allowed to establish WebSocket connections directly. Attempts return HTTP 403.
  • Only sub keys are allowed to establish WebSocket connections.

Example: ws_conn_limit = 2

ActionResult
1st WS connection (/hl/ws)✅ Success
2nd WS connection (/hl/ws/fills)✅ Success (shared across paths)
3rd WS connection (/hl/ws/filled-orders)❌ HTTP 429
Close the 1st connection and retry after a few seconds✅ Success

WebSocket Subscription Limits

After a WebSocket connection is established, clients subscribe to different data channels by sending subscribe messages. The number of subscriptions is limited by ws_sub_limit.

Sub Key Subscription Limit

  • When creating a sub key, you can set ws_sub_limit to define the maximum number of WebSocket subscriptions allowed for that sub key.
  • All WS connections under the same sub key share the same subscription counter: regardless of how many connections are open, the total number of subscriptions cannot exceed ws_sub_limit.
  • When the limit is exceeded, the server returns {"error": "subscription limit exceeded", "limit": N, "current": N} and the subscription is not applied.
  • Clients can send unsubscribe messages to release subscription slots, after which new subscriptions can be created.
  • When a connection closes, whether normally or unexpectedly, all subscriptions on that connection are released automatically.

Subscription Types

Each subscribe message counts as one subscription, regardless of the subscription type (trades, l2Book, candle, and so on). Subscriptions of the same type but with different parameters, such as different coins, are counted independently.

Example: ws_sub_limit = 5

ActionResult
Subscribe to {"method":"subscribe","subscription":{"type":"trades","coin":"BTC"}}✅ Success (1/5)
Subscribe to {"method":"subscribe","subscription":{"type":"trades","coin":"ETH"}}✅ Success (2/5)
Subscribe to {"method":"subscribe","subscription":{"type":"trades","coin":"SOL"}}✅ Success (3/5)
Subscribe to {"method":"subscribe","subscription":{"type":"trades","coin":"DOGE"}}✅ Success (4/5)
Subscribe to {"method":"subscribe","subscription":{"type":"trades","coin":"XRP"}}✅ Success (5/5)
Subscribe to {"method":"subscribe","subscription":{"type":"trades","coin":"AVAX"}}❌ Returns subscription limit exceeded
Unsubscribe from {"method":"unsubscribe","subscription":{"type":"trades","coin":"DOGE"}}✅ One slot released (4/5)
Subscribe again to {"method":"subscribe","subscription":{"type":"trades","coin":"AVAX"}}✅ Success (5/5)
Connection closesSubscriptions on that connection are automatically released

Notes

  • When ws_sub_limit is 0 or unset, there is no subscription count limit.
  • The subscription limit and the connection limit (ws_conn_limit) are independent dimensions and do not affect each other.
  • Plan subscriptions carefully to avoid wasting slots on channels you do not need.

Maximum Query Time Range (max_time_range)

Endpoints that accept start_time and end_time parameters, such as historical whale long-short ratio and candlestick endpoints, are restricted by max_time_range to prevent excessively large ranges in a single request.

Limit Sources

max_time_range is determined by two layers, and the stricter value takes effect:

LayerConfig LocationDescription
LevelSet request_limits.max_time_range via the "Create or Update Level Configuration" endpointDefault time-range upper bound for all sub keys under this level
Sub keySet max_time_range when creating or updating a sub keyCan further tighten the level restriction, but cannot relax it

Effective Rule

effective_max_time_range = min(level_config, subkey_override)
  • If the sub key's max_time_range = 0, no sub-key-level override is applied and the level configuration is used directly.
  • If the level's max_time_range = 0, the level does not impose a limit and the sub key value applies.
  • If both are 0, there is no time-range restriction.
  • A sub key value can only be stricter (smaller) than the level value, not looser. For example, if the level is 1 day (86400 seconds) and the sub key is 7 days (604800 seconds), the effective limit is still 1 day.

Examples

Level max_time_rangeSub key max_time_rangeEffective Limit31-day Request
2592000 (30 days)0 (no override)30 days❌ 400
2592000 (30 days)86400 (1 day)1 day❌ 400
3600 (1 hour)604800 (7 days)1 hour (level is stricter)❌ 400
0 (unlimited)0 (no override)Unlimited✅ 200
0 (unlimited)86400 (1 day)1 day❌ 400

Response When the Limit Is Exceeded

When the requested time range exceeds max_time_range, the server returns HTTP 400:

{
  "success": false,
  "error": "time range exceeded"
}

Common max_time_range Reference Values

Time SpanSeconds
1 hour3600
1 day86400
7 days604800
30 days2592000
365 days31536000

Tip: Changes to max_time_range take effect immediately. No restart or waiting period is required. You can adjust it at any time through the "Update Level Configuration" or "Update Sub Key" endpoints.

HTTP Error Code Conventions

  • 200: Success
  • 400: Invalid parameters
  • 401: Signature authentication failed (missing parameters, expired timestamp, invalid signature, or invalid access key)
  • 403: Insufficient permissions (not a distributor, distributor disabled, sub key disabled or expired, distributor primary key accessing non-management endpoints, and so on)
  • 429: Rate limit or quota limit triggered, including WebSocket connection limit overages
  • 500: Internal server error

Was this page helpful?