BBX 开放API 文档

分销机构管理 API

分销机构 API 允许合作伙伴自主管理 API Key，为其客户创建和分发子 Key，实现独立的用户管理和配额控制。

基础信息

说明：

  • 签名参数（AccessKeyId / SignatureNonce / Timestamp / Signature）统一放在 URL Query。签名计算仅使用以下字符串（顺序固定）：AccessKeyId={AccessKeyId}&SignatureNonce={SignatureNonce}&Timestamp={Timestamp}，再用 SecretKey 进行 HmacSHA1 后取 hex digest，最后对 hex 字符串进行 Base64。
  • 业务参数放在请求体 JSON（仅 POST/PUT 接口）。
  • GET 请求的所有业务参数均放在 URL Query。

请求必带参数

管理 API 的每个请求需要携带：

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

分销商自助注册（邀请码）

使用管理员提供的邀请码（Invite Token）自助注册成为分销商，获取专属的 AccessKey 和 SecretKey。

此接口为公开接口，无需签名鉴权。

邀请码机制说明

  • 邀请码由管理员预先生成，包含分销商预设配置（名称、等级、子 Key 上限、月度总额度、WS 连接/订阅上限等）。
  • 一次性有效：邀请码在成功注册后立即失效，不可重复使用。
  • 使用无效或已消费的邀请码将返回 400 错误。
  • 注册成功后，分销商需要通过 创建或更新档位配置 接口为子 Key 配置档位（Level），设定权限（permissions）和限额模板（request_limits）。未配置档位权限的子 Key 将无法访问任何数据接口（返回 403）。

请求参数

  • Name
    invite_token
    Type
    string
    Description
    管理员提供的邀请码（必填）

返回数据

  • Name
    success
    Type
    boolean
    Description
    接口状态
  • Name
    data
    Type
    object
    Description

    返回数据

    • Name
      access_key
      Type
      string
      Description
      分销机构 AccessKey
    • Name
      secret_key
      Type
      string
      Description
      分销机构 SecretKey（仅此一次展示，请妥善保管）
    • Name
      name
      Type
      string
      Description
      分销机构名称（由邀请码预设）
    • Name
      level
      Type
      string
      Description
      分销机构等级（由邀请码预设）
  • Name
    message
    Type
    string
    Description
    操作结果描述

重要：secret_key 仅在注册成功时返回一次，之后无法再次获取。请务必在收到响应后立即安全保存。

请求

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

响应（成功）

{
  "success": true,
  "data": {
    "access_key": "dist_ak_xxxx",
    "secret_key": "dist_sk_xxxx",
    "name": "Partner-Alpha",
    "level": "standard"
  },
  "message": "分销商注册成功，请妥善保管 SecretKey，此密钥仅展示一次"
}

响应（邀请码无效或已使用）

{
  "success": false,
  "error": "邀请码无效或已过期"
}
GET/api/upgrade/v2/distributor/info

获取分销机构信息

获取当前分销机构的基础信息（包含子 Key 上限与月度总额度）。

请求参数

  • Name
    AccessKeyId
    Type
    string
    Description
    分销机构主 AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    签名随机数
  • Name
    Timestamp
    Type
    string
    Description
    请求时间戳(秒)
  • Name
    Signature
    Type
    string
    Description
    使用 HmacSHA1 + Base64 生成的签名

返回数据

  • Name
    success
    Type
    boolean
    Description
    接口状态
  • Name
    data
    Type
    object
    Description

    返回数据

    • Name
      access_key
      Type
      string
      Description
      分销机构 AccessKey
    • Name
      name
      Type
      string
      Description
      分销机构名称
    • Name
      level
      Type
      string
      Description
      分销机构自身等级
    • Name
      max_sub_keys
      Type
      integer
      Description
      允许创建的子 Key 数量上限
    • Name
      sub_key_count
      Type
      integer
      Description
      当前已创建的子 Key 数量
    • Name
      max_total_quota
      Type
      integer
      Description
      分销机构月度总额度上限

请求

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

响应

{
  "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

获取配额详情

获取分销机构维度的月度配额对账信息（含已分配/可分配/已消耗/剩余）。

请求参数

  • Name
    AccessKeyId
    Type
    string
    Description
    分销机构主 AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    签名随机数
  • Name
    Timestamp
    Type
    string
    Description
    请求时间戳(秒)
  • Name
    Signature
    Type
    string
    Description
    使用 HmacSHA1 + Base64 生成的签名

说明：

  • max_total_quota 是分销机构维度的“总月度请求数硬上限”（所有子 Key 合计消耗）。
  • allocated_quota 是当前已分配给所有子 Key 的月度额度总和。
  • available_quota 是当前分销机构剩余可分配给子 Key 的月度额度 (max_total_quota - allocated_quota)。
  • used_quota 是本月所有子 Key 累计已消耗的请求总数。
  • remaining_quota 是本月分销机构总额度下剩余可用的请求数 (max(max_total_quota - used_quota, 0))。

返回数据

  • Name
    success
    Type
    boolean
    Description
    接口状态
  • Name
    data
    Type
    object
    Description

    返回数据

    • Name
      max_total_quota
      Type
      integer
      Description
      合同约定的月度总请求额度上限
    • Name
      allocated_quota
      Type
      integer
      Description
      已分配给所有子 Key 的月度额度总和
    • Name
      available_quota
      Type
      integer
      Description
      剩余可分配配额
    • Name
      used_quota
      Type
      integer
      Description
      本月已真实消耗的请求数（所有子 Key 合计）
    • Name
      remaining_quota
      Type
      integer
      Description
      本月剩余可用请求数

请求

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

响应

{
  "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

列出可用档位

用于列出当前分销机构已经配置过的 level 名称列表。

请求参数

  • Name
    AccessKeyId
    Type
    string
    Description
    分销机构主 AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    签名随机数
  • Name
    Timestamp
    Type
    string
    Description
    请求时间戳(秒)
  • Name
    Signature
    Type
    string
    Description
    使用 HmacSHA1 + Base64 生成的签名

返回数据

  • Name
    success
    Type
    boolean
    Description
    接口状态
  • Name
    data
    Type
    array
    Description
    档位名称列表

请求

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

响应

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

获取档位配置

返回指定档位的“配额模板 + 权限集合”。

请求参数

  • Name
    level
    Type
    string
    Description
    档位名称（路径参数）
  • Name
    AccessKeyId
    Type
    string
    Description
    分销机构主 AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    签名随机数
  • Name
    Timestamp
    Type
    string
    Description
    请求时间戳(秒)
  • Name
    Signature
    Type
    string
    Description
    使用 HmacSHA1 + Base64 生成的签名

返回数据

  • Name
    success
    Type
    boolean
    Description
    接口状态
  • Name
    data
    Type
    object
    Description

    返回数据

    • Name
      request_limits
      Type
      object
      Description

      限额模板

      • Name
        max_time_range
        Type
        integer
        Description
        最大查询时间跨度（秒）
      • Name
        max_request
        Type
        integer
        Description
        默认月度请求限额
      • Name
        request_rate_limit
        Type
        integer
        Description
        每分钟请求速率限制（QPM）
    • Name
      permissions
      Type
      array
      Description
      权限集合（resource_type + actions）

请求

GET
/api/upgrade/v2/distributor/levels/:level
curl -G https://open.aicoin.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"

响应

{
  "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

创建或更新档位配置

创建或更新指定档位的“限额模板 + 权限集合”。

请求参数

  • Name
    level
    Type
    string
    Description
    档位名称（路径参数）
  • Name
    request_limits
    Type
    object
    Description
    限额模板
  • Name
    permissions
    Type
    array
    Description
    权限集合（resource_type + actions）
  • Name
    AccessKeyId
    Type
    string
    Description
    分销机构主 AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    签名随机数
  • Name
    Timestamp
    Type
    string
    Description
    请求时间戳(秒)
  • Name
    Signature
    Type
    string
    Description
    使用 HmacSHA1 + Base64 生成的签名

说明：

  • permissions 用于配置该档位允许访问的接口集合。
  • request_limits 用于配置该档位的限额模板。

permissions 字段数据结构

permissions 是一个数组，每个元素包含：

  • resource_type（string）：固定为 "hyperliquid"，分销商仅允许配置 Hyperliquid 模块的权限，传入其他值（如 futures、trading_pair）会返回 400 错误。
  • actions（string[]）：该资源类型下允许访问的操作列表，取值见下方"可用 Actions 列表"。

由于 resource_type 固定为 hyperliquid，实际使用时只需关注 actions 即可。

request_limits 字段

字段类型说明
max_time_rangeinteger最大可查询时间范围（秒）
max_requestinteger月度最大请求数
request_rate_limitinteger每分钟请求频率限制

权限与接口的关联机制

每个 API 接口在服务端注册时绑定了一组 (resource_type, action)。当子 Key 发起请求时，系统会检查其所属档位的 permissions 中是否包含该接口对应的 action——有则放行，无则返回 403。

简单来说：一个接口对应一个 action，档位的 permissions 决定了子 Key 能调用哪些接口。

重要：新增接口与档位更新

当平台后续上线新的 API 接口时，会同步新增对应的 Action。已有的档位配置不会自动包含新 Action，分销商需要主动调用本接口（PUT /api/upgrade/v2/distributor/levels/:level）将新 Action 添加到 permissions 中，其子 Key 才能访问新接口。

建议分销商在收到新接口上线通知后，及时更新各档位的权限配置。

可用 Actions 列表

下表列出了每个 action 对应的 API 接口：

数据查询类

Action对应接口
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

聪明钱 / 鲸鱼类

Action对应接口
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_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

强平 / TWAP 类

Action对应接口
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（批量查询地址交易统计）
HL_WS_CLEARINGHOUSE_STATEGET /hl/ws/clearinghouse-state（WebSocket 订阅账户状态）

Info API 代理类

Action对应接口
HL_INFOPOST /hl/info（统一端点，通过请求体 type 字段路由）
HL_INFO_BATCH_CLEARINGHOUSE_STATEPOST /hl/traders/clearinghouse-state（批量查询永续账户状态）
HL_INFO_BATCH_SPOT_CLEARINGHOUSE_STATEPOST /hl/traders/spot-clearinghouse-state（批量查询现货账户状态）

注意：HL_INFO 是 POST /hl/info 统一端点的唯一权限控制点。拥有 HL_INFO 权限即可访问该端点下的所有子类型（包括 meta、spotMeta、clearinghouseState、webData2、userFills 等）。目前不支持按 type 做更细粒度的权限拆分。下方的 HL_INFO_* 系列 action 仅用于未来扩展预留，当前配置它们不会产生额外效果。

HL_INFO 细粒度权限（预留）

Action说明
HL_INFO_META元数据查询
HL_INFO_SPOT_META现货元数据查询
HL_INFO_CLEARINGHOUSE_STATE单地址永续账户状态
HL_INFO_SPOT_CLEARINGHOUSE_STATE单地址现货账户状态
HL_INFO_OPEN_ORDERS当前挂单查询
HL_INFO_FRONTEND_OPEN_ORDERS前端挂单查询
HL_INFO_USER_FEES用户费率查询
HL_INFO_USER_FILLS用户成交记录
HL_INFO_USER_FILLS_BY_TIME按时间查询成交记录
HL_INFO_CANDLE_SNAPSHOTK线快照
HL_INFO_PERP_DEXS永续 DEX 列表
HL_INFO_ACTIVE_ASSET_DATA活跃资产数据
HL_INFO_WEB_DATA2网页数据
HL_INFO_HISTORICAL_ORDERS历史订单
HL_INFO_USER_TWAP_SLICE_FILLSTWAP 切片成交
HL_INFO_ORDER_STATUS订单状态
HL_INFO_USER_FUNDING用户资金费率
HL_INFO_USER_NON_FUNDING_LEDGER_UPDATES非资金账本更新

WebSocket 类

Action对应接口
HL_WS_NODEGET /hl/ws
HL_WS_FILLSGET /hl/ws/fills
HL_WS_FILLED_ORDERSGET /hl/ws/filled-orders

注意：WebSocket 连接受额外的并发数限制，详见下方 WebSocket 连接限制 章节。

返回数据

  • Name
    success
    Type
    boolean
    Description
    接口状态
  • Name
    message
    Type
    string
    Description
    操作结果描述

请求

PUT
/api/upgrade/v2/distributor/levels/:level
curl -X PUT 'https://open.aicoin.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"
        ]
      }
    ]
  }'

响应

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

删除档位配置

删除指定档位的配置（权限集合与配额模板）。

请求参数

  • Name
    level
    Type
    string
    Description
    档位名称（路径参数）
  • Name
    AccessKeyId
    Type
    string
    Description
    分销机构主 AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    签名随机数
  • Name
    Timestamp
    Type
    string
    Description
    请求时间戳(秒)
  • Name
    Signature
    Type
    string
    Description
    使用 HmacSHA1 + Base64 生成的签名

返回数据

  • Name
    success
    Type
    boolean
    Description
    接口状态
  • Name
    message
    Type
    string
    Description
    操作结果描述

请求

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

响应

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

创建子 Key

创建一个子 Key 并分配其独立配额与限流参数。

Level 设置说明

创建子 Key 时支持传入 level 字段，用于指定该子 Key 使用的档位（权限集合 + 配额模板）。

  • 不传 level 或传空字符串：默认继承分销机构自身的 level
  • 传入 level：使用指定的档位（建议先通过"创建或更新档位配置"接口配置好对应档位）

请求参数

  • Name
    name
    Type
    string
    Description
    子 Key 名称
  • Name
    level
    Type
    string
    Description
    档位名称（可选，不传则继承分销机构自身 level）
  • Name
    monthly_quota
    Type
    integer
    Description
    子 Key 月度配额（可选，不传走默认/自动分配；显式传入时必须>=1）
  • Name
    rate_limit
    Type
    integer
    Description
    每分钟请求限制（QPM）
  • Name
    max_time_range
    Type
    integer
    Description
    最大查询时间跨度（秒）
  • Name
    ws_conn_limit
    Type
    integer
    Description
    WebSocket 最大并发连接数（可选，不传或传 0 表示不限制）
  • Name
    ws_sub_limit
    Type
    integer
    Description
    WebSocket 最大订阅数（可选，不传或传 0 表示不限制）
  • Name
    expires_in
    Type
    integer
    Description
    有效期（秒）
  • Name
    metadata
    Type
    string
    Description
    扩展信息（JSON string）
  • Name
    AccessKeyId
    Type
    string
    Description
    分销机构主 AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    签名随机数
  • Name
    Timestamp
    Type
    string
    Description
    请求时间戳(秒)
  • Name
    Signature
    Type
    string
    Description
    使用 HmacSHA1 + Base64 生成的签名

说明：

  • secret_key 仅在创建时返回一次，如遗失需使用"重置密钥"接口。
  • monthly_quota：
    • 显式传入时必须 >=1，否则返回 400，错误信息：子Key月度额度必须>=1。
    • 不传时：
      • 若分销机构配置了 max_total_quota > 0，默认分配当前剩余可分配额度（available_quota = max_total_quota - allocated_quota）。
      • 若 max_total_quota == 0，使用系统默认值（当前默认 1000）。
  • 子 Key 实际消耗时，不仅受自身 monthly_quota 限制，还受分销商 max_total_quota 的硬上限限制。
  • ws_conn_limit（可选）：该子 Key 允许的 WebSocket 最大并发连接数。不传或传 0 表示不限制。详见 WebSocket 连接限制。
  • ws_sub_limit（可选）：该子 Key 允许的 WebSocket 最大订阅数（单连接内的 subscribe 总数）。不传或传 0 表示不限制。详见 WebSocket 订阅数限制。

返回数据

  • Name
    success
    Type
    boolean
    Description
    接口状态
  • Name
    data
    Type
    object
    Description

    返回数据

    • Name
      access_key
      Type
      string
      Description
      子 AccessKey
    • Name
      secret_key
      Type
      string
      Description
      子 SecretKey（仅创建时返回）
    • Name
      name
      Type
      string
      Description
      子 Key 名称
    • Name
      level
      Type
      string
      Description
      子 Key 等级
    • Name
      created_at
      Type
      string
      Description
      创建时间（RFC3339）
    • Name
      expires_at
      Type
      string
      Description
      过期时间（RFC3339，可为 null）
  • Name
    message
    Type
    string
    Description
    操作结果描述

请求

POST
/api/upgrade/v2/distributor/sub-keys
curl -X POST 'https://open.aicoin.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": "客户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\"}"
  }'

响应

{
  "success": true,
  "data": {
    "access_key": "sub_ak_xxxx",
    "secret_key": "sub_sk_xxxx",
    "name": "客户A的API Key",
    "level": "gold",
    "created_at": "2026-01-29T14:30:15+08:00",
    "expires_at": null
  },
  "message": "子Key创建成功，请妥善保管SecretKey"
}

子 Key 状态编码

子 Key 的 status 字段取值如下：

status含义
1启用（Active）
0禁用（Disabled）

说明：

  • 子 Key 创建后默认 status=1。
  • 当 status=0（禁用）时，该子 Key 的所有请求将被拒绝（通常返回 403）。
GET/api/upgrade/v2/distributor/sub-keys

获取子 Key 列表

获取子 Key 列表，支持分页与筛选。

请求参数

  • Name
    page
    Type
    integer
    Description
    页码
  • Name
    page_size
    Type
    integer
    Description
    每页条数
  • Name
    status
    Type
    integer
    Description
    状态筛选（可选）
  • Name
    keyword
    Type
    string
    Description
    关键字筛选（可选）
  • Name
    AccessKeyId
    Type
    string
    Description
    分销机构主 AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    签名随机数
  • Name
    Timestamp
    Type
    string
    Description
    请求时间戳(秒)
  • Name
    Signature
    Type
    string
    Description
    使用 HmacSHA1 + Base64 生成的签名

返回数据

  • Name
    success
    Type
    boolean
    Description
    接口状态
  • Name
    data
    Type
    object
    Description

    返回数据

    • Name
      list
      Type
      array
      Description
      子 Key 列表
    • Name
      total
      Type
      integer
      Description
      总数
    • Name
      page
      Type
      integer
      Description
      当前页码
    • Name
      page_size
      Type
      integer
      Description
      每页条数

请求

GET
/api/upgrade/v2/distributor/sub-keys
curl -G https://open.aicoin.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"

响应

{
  "success": true,
  "data": {
    "list": [
      {
        "access_key": "sub_ak_xxxx",
        "name": "客户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

获取子 Key 详情

获取指定子 Key 的详细信息。

请求参数

  • Name
    access_key
    Type
    string
    Description
    子 AccessKey（路径参数）
  • Name
    AccessKeyId
    Type
    string
    Description
    分销机构主 AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    签名随机数
  • Name
    Timestamp
    Type
    string
    Description
    请求时间戳(秒)
  • Name
    Signature
    Type
    string
    Description
    使用 HmacSHA1 + Base64 生成的签名

返回数据

  • Name
    success
    Type
    boolean
    Description
    接口状态
  • Name
    data
    Type
    object
    Description
    子 Key 详情

请求

GET
/api/upgrade/v2/distributor/sub-keys/:access_key
curl -G https://open.aicoin.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"

响应

{
  "success": true,
  "data": {
    "access_key": "sub_ak_xxxx",
    "name": "客户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

更新子 Key

更新指定子 Key 的配置。

请求参数

  • Name
    access_key
    Type
    string
    Description
    子 AccessKey（路径参数）
  • Name
    name
    Type
    string
    Description
    子 Key 名称（可选）
  • Name
    status
    Type
    integer
    Description
    状态（可选，0=禁用，1=启用）
  • Name
    monthly_quota
    Type
    integer
    Description
    月度配额（可选）
  • Name
    rate_limit
    Type
    integer
    Description
    QPM 限流（可选）
  • Name
    max_time_range
    Type
    integer
    Description
    最大查询时间跨度（秒，可选）
  • Name
    ws_conn_limit
    Type
    integer
    Description
    WebSocket 最大并发连接数（可选，0 表示不限制）
  • Name
    ws_sub_limit
    Type
    integer
    Description
    WebSocket 最大订阅数（可选，0 表示不限制）
  • Name
    expires_in
    Type
    integer
    Description
    有效期（秒，从当前时间开始；传 0 表示清空有效期）
  • Name
    metadata
    Type
    string
    Description
    扩展信息（JSON string，可选）
  • Name
    AccessKeyId
    Type
    string
    Description
    分销机构主 AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    签名随机数
  • Name
    Timestamp
    Type
    string
    Description
    请求时间戳(秒)
  • Name
    Signature
    Type
    string
    Description
    使用 HmacSHA1 + Base64 生成的签名

返回数据

  • Name
    success
    Type
    boolean
    Description
    接口状态
  • Name
    message
    Type
    string
    Description
    操作结果描述

请求

PUT
/api/upgrade/v2/distributor/sub-keys/:access_key
curl -X PUT 'https://open.aicoin.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}'

响应

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

删除子 Key

删除指定子 Key。

请求参数

  • Name
    access_key
    Type
    string
    Description
    子 AccessKey（路径参数）
  • Name
    AccessKeyId
    Type
    string
    Description
    分销机构主 AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    签名随机数
  • Name
    Timestamp
    Type
    string
    Description
    请求时间戳(秒)
  • Name
    Signature
    Type
    string
    Description
    使用 HmacSHA1 + Base64 生成的签名

返回数据

  • Name
    success
    Type
    boolean
    Description
    接口状态
  • Name
    message
    Type
    string
    Description
    操作结果描述

请求

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

响应

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

启用子 Key

启用指定子 Key。

请求参数

  • Name
    access_key
    Type
    string
    Description
    子 AccessKey（路径参数）
  • Name
    AccessKeyId
    Type
    string
    Description
    分销机构主 AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    签名随机数
  • Name
    Timestamp
    Type
    string
    Description
    请求时间戳(秒)
  • Name
    Signature
    Type
    string
    Description
    使用 HmacSHA1 + Base64 生成的签名

返回数据

  • Name
    success
    Type
    boolean
    Description
    接口状态
  • Name
    message
    Type
    string
    Description
    操作结果描述

请求

POST
/api/upgrade/v2/distributor/sub-keys/:access_key/enable
curl -X POST 'https://open.aicoin.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'

响应

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

禁用子 Key

禁用指定子 Key。

请求参数

  • Name
    access_key
    Type
    string
    Description
    子 AccessKey（路径参数）
  • Name
    AccessKeyId
    Type
    string
    Description
    分销机构主 AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    签名随机数
  • Name
    Timestamp
    Type
    string
    Description
    请求时间戳(秒)
  • Name
    Signature
    Type
    string
    Description
    使用 HmacSHA1 + Base64 生成的签名

返回数据

  • Name
    success
    Type
    boolean
    Description
    接口状态
  • Name
    message
    Type
    string
    Description
    操作结果描述

请求

POST
/api/upgrade/v2/distributor/sub-keys/:access_key/disable
curl -X POST 'https://open.aicoin.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'

响应

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

重置子 Key 密钥

重置指定子 Key 的密钥，重置后原 SecretKey 立即失效。

请求参数

  • Name
    access_key
    Type
    string
    Description
    子 AccessKey（路径参数）
  • Name
    AccessKeyId
    Type
    string
    Description
    分销机构主 AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    签名随机数
  • Name
    Timestamp
    Type
    string
    Description
    请求时间戳(秒)
  • Name
    Signature
    Type
    string
    Description
    使用 HmacSHA1 + Base64 生成的签名

返回数据

  • Name
    success
    Type
    boolean
    Description
    接口状态
  • Name
    data
    Type
    object
    Description

    返回数据

    • Name
      access_key
      Type
      string
      Description
      子 AccessKey
    • Name
      secret_key
      Type
      string
      Description
      新的子 SecretKey
  • Name
    message
    Type
    string
    Description
    操作结果描述

请求

POST
/api/upgrade/v2/distributor/sub-keys/:access_key/reset-secret
curl -X POST 'https://open.aicoin.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'

响应

{
  "success": true,
  "data": {
    "access_key": "sub_ak_xxxx",
    "secret_key": "new_sub_sk_xxxx"
  },
  "message": "子Key密钥重置成功，请妥善保管新的SecretKey"
}
GET/api/upgrade/v2/distributor/sub-keys/stats

子 Key 统计

获取子 Key 总数、启用/禁用数，以及分销机构月度额度使用概览。

请求参数

  • Name
    AccessKeyId
    Type
    string
    Description
    分销机构主 AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    签名随机数
  • Name
    Timestamp
    Type
    string
    Description
    请求时间戳(秒)
  • Name
    Signature
    Type
    string
    Description
    使用 HmacSHA1 + Base64 生成的签名

返回数据

  • Name
    success
    Type
    boolean
    Description
    接口状态
  • Name
    data
    Type
    object
    Description
    统计数据

请求

GET
/api/upgrade/v2/distributor/sub-keys/stats
curl -G https://open.aicoin.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"

响应

{
  "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

批量启用子 Key

批量启用多个子 Key。

请求参数

  • Name
    access_keys
    Type
    array
    Description
    需要启用的子 AccessKey 列表
  • Name
    AccessKeyId
    Type
    string
    Description
    分销机构主 AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    签名随机数
  • Name
    Timestamp
    Type
    string
    Description
    请求时间戳(秒)
  • Name
    Signature
    Type
    string
    Description
    使用 HmacSHA1 + Base64 生成的签名

返回数据

  • Name
    success
    Type
    boolean
    Description
    接口状态
  • Name
    message
    Type
    string
    Description
    操作结果描述

请求

POST
/api/upgrade/v2/distributor/sub-keys/batch-enable
curl -X POST 'https://open.aicoin.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"]}'

响应

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

批量禁用子 Key

批量禁用多个子 Key。

请求参数

  • Name
    access_keys
    Type
    array
    Description
    需要禁用的子 AccessKey 列表
  • Name
    AccessKeyId
    Type
    string
    Description
    分销机构主 AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    签名随机数
  • Name
    Timestamp
    Type
    string
    Description
    请求时间戳(秒)
  • Name
    Signature
    Type
    string
    Description
    使用 HmacSHA1 + Base64 生成的签名

返回数据

  • Name
    success
    Type
    boolean
    Description
    接口状态
  • Name
    message
    Type
    string
    Description
    操作结果描述

请求

POST
/api/upgrade/v2/distributor/sub-keys/batch-disable
curl -X POST 'https://open.aicoin.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"]}'

响应

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

导出子 Key

导出子 Key 数据，返回 JSON 文件内容。

请求参数

  • Name
    keyword
    Type
    string
    Description
    关键字筛选（可选）
  • Name
    AccessKeyId
    Type
    string
    Description
    分销机构主 AccessKeyId
  • Name
    SignatureNonce
    Type
    string
    Description
    签名随机数
  • Name
    Timestamp
    Type
    string
    Description
    请求时间戳(秒)
  • Name
    Signature
    Type
    string
    Description
    使用 HmacSHA1 + Base64 生成的签名

返回数据

  • Name
    body
    Type
    array
    Description
    导出的子 Key 数据列表（响应体为 JSON 数组）

请求

GET
/api/upgrade/v2/distributor/sub-keys/export
curl -G https://open.aicoin.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"

响应（文件内容示例）

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

WebSocket 连接限制

WebSocket 接口（GET /hl/ws、GET /hl/ws/fills、GET /hl/ws/filled-orders）受以下连接限制：

子 Key 连接上限

  • 创建子 Key 时可通过 ws_conn_limit 字段设置该子 Key 允许的 最大并发 WebSocket 连接数。
  • 所有 WS 路径共享同一个连接计数：/hl/ws + /hl/ws/fills + /hl/ws/filled-orders 的连接总数不能超过 ws_conn_limit。
  • 超出限制时，新连接请求将返回 HTTP 429，错误信息：ws connection limit exceeded for sub key。
  • 断开已有连接后，对应的连接槽位会在数秒内自动释放，之后即可建立新连接。

分销商主 Key 限制

  • 分销商主 Key 不允许直接建立 WebSocket 连接，尝试时返回 HTTP 403。
  • 仅子 Key 可以建立 WebSocket 连接。

示例：ws_conn_limit = 2

操作结果
第 1 个 WS 连接（/hl/ws）✅ 成功
第 2 个 WS 连接（/hl/ws/fills）✅ 成功（跨路径也计数）
第 3 个 WS 连接（/hl/ws/filled-orders）❌ HTTP 429
关闭第 1 个连接，等待几秒后重试✅ 成功

WebSocket 订阅数限制

在 WebSocket 连接建立后，客户端通过发送 subscribe 消息来订阅不同的数据频道。订阅数量受 ws_sub_limit 限制。

子 Key 订阅上限

  • 创建子 Key 时可通过 ws_sub_limit 字段设置该子 Key 允许的 最大 WebSocket 订阅数。
  • 同一子 Key 的所有 WS 连接共享同一个订阅计数：无论分布在多少个连接中，subscribe 的总数不能超过 ws_sub_limit。
  • 超出限制时，服务端会返回错误消息：{"error": "subscription limit exceeded", "limit": N, "current": N}，该订阅不会生效。
  • 客户端可以通过发送 unsubscribe 消息释放订阅槽位，之后即可订阅新的频道。
  • 当连接断开（正常关闭或异常断开）时，该连接上的所有订阅会自动释放。

订阅类型

每个 subscribe 消息算作 1 个订阅，无论订阅的类型是什么（如 trades、l2Book、candle 等）。相同类型但不同参数（如不同币种）的订阅各自独立计数。

示例：ws_sub_limit = 5

操作结果
订阅 {"method":"subscribe","subscription":{"type":"trades","coin":"BTC"}}✅ 成功（1/5）
订阅 {"method":"subscribe","subscription":{"type":"trades","coin":"ETH"}}✅ 成功（2/5）
订阅 {"method":"subscribe","subscription":{"type":"trades","coin":"SOL"}}✅ 成功（3/5）
订阅 {"method":"subscribe","subscription":{"type":"trades","coin":"DOGE"}}✅ 成功（4/5）
订阅 {"method":"subscribe","subscription":{"type":"trades","coin":"XRP"}}✅ 成功（5/5）
订阅 {"method":"subscribe","subscription":{"type":"trades","coin":"AVAX"}}❌ 返回 subscription limit exceeded
取消订阅 {"method":"unsubscribe","subscription":{"type":"trades","coin":"DOGE"}}✅ 释放 1 个槽位（4/5）
重新订阅 {"method":"subscribe","subscription":{"type":"trades","coin":"AVAX"}}✅ 成功（5/5）
连接断开该连接上的订阅自动释放

注意事项

  • ws_sub_limit 为 0 或未设置时，表示不限制订阅数量。
  • 订阅数限制与连接数限制（ws_conn_limit）是独立的两个维度，两者互不影响。
  • 建议合理规划订阅数量，避免订阅不需要的频道浪费槽位。

最大查询时间范围限制（max_time_range）

带有 start_time 和 end_time 参数的接口（如历史鲸鱼多空比、K 线数据等）受 max_time_range 限制，防止单次请求跨度过大。

限制来源

max_time_range 由两个层级共同决定，取更严格的值生效：

层级配置位置说明
档位（Level）通过"创建或更新档位配置"接口设置 request_limits.max_time_range该档位下所有子 Key 的默认时间范围上限
子 Key创建/更新子 Key 时设置 max_time_range可进一步收紧（但不能放宽）档位限制

生效规则

effective_max_time_range = min(level_config, subkey_override)
  • 子 Key 的 max_time_range = 0：表示不做子 Key 级别覆盖，直接使用档位配置。
  • 档位的 max_time_range = 0：表示档位不限制，此时子 Key 的值生效。
  • 两者都为 0：不限制时间范围。
  • 子 Key 设置的值只能比档位更严格（更小），不能放宽。例如档位为 1 天（86400 秒），子 Key 设为 7 天（604800 秒），实际仍按 1 天执行。

示例

档位 max_time_range子 Key max_time_range实际生效请求 31 天
2592000（30 天）0（不覆盖）30 天❌ 400
2592000（30 天）86400（1 天）1 天❌ 400
3600（1 小时）604800（7 天）1 小时（档位更严）❌ 400
0（不限制）0（不覆盖）不限制✅ 200
0（不限制）86400（1 天）1 天❌ 400

触发限制时的响应

当请求的时间范围超过 max_time_range 时，返回 HTTP 400：

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

常用 max_time_range 参考值

时间跨度秒数
1 小时3600
1 天86400
7 天604800
30 天2592000
365 天31536000

提示：max_time_range 的修改实时生效，无需重启或等待。可通过"更新档位配置"或"更新子 Key"接口随时调整。

错误码约定（HTTP）

  • 200：成功
  • 400：参数错误
  • 401：签名认证失败（缺参/时间戳过期/签名错误/无效 access key）
  • 403：权限不足（非分销机构/机构被禁用/子 key 被禁用或过期/分销主 key 访问非管理接口等）
  • 429：频率或配额限制触发（含 WebSocket 连接数超限）
  • 500：内部错误

您对本页面是否满意？