代理人接口
代理人 OpenAPI 使用 /api/v1/agent 前缀。所有接口都需要 API Key 签名，适用于已开通代理人能力的账户。
- 所有接口均为
GET，业务参数通过 query string 传递。 - 所有接口都需要签名，公共签名规则请参考基础信息。
- 所有接口均限制为每秒最多请求 1 次，接口权重为
1。 - 除特别说明外，时间字段均为毫秒级 UNIX 时间戳。
- 除接口另有说明外，分页接口的
pageIndex默认1，pageSize默认100，取值范围为100到200。
公共签名参数
| 参数名称 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
| recvWindow | LONG | NO | 请求有效时间窗口，单位毫秒；未传时默认 5000 |
| timestamp | LONG | YES | 请求时间戳，单位毫秒 |
| signature | STRING | YES | 使用 API Secret 对请求参数计算得到的 HMAC SHA256 签名 |
通用响应结构
成功响应统一返回：
json
{
"code": 200,
"msg": "success",
"data": {}
}分页接口的 data 为分页对象：
| 字段 | 类型 | 说明 |
|---|---|---|
| pages | string | 总页数 |
| total | string | 总条数 |
| list | array | 当前页数据 |
使用游标分页的接口以对应章节的响应结构为准。
通用错误码
| code | msg | 说明 |
|---|---|---|
| 200 | success | 成功 |
| -1001 | Internal error. | 内部错误或下游服务异常 |
| -1003 | Too many requests... | 超过代理人接口限频 |
| -1020 | This operation is not supported. | 当前 API Key 不支持该操作，例如只读 API Key 调用导出申请 |
| -1021 | Timestamp for this request is outside of the recvWindow. | 时间戳超出有效窗口 |
| -1022 | Signature for this request is not valid. | 签名无效 |
| -1115 | Invalid timeInForce. | 时间范围不合法，代理人接口中也用于时间窗口校验失败 |
| -1130 | Data sent for paramter ... is not valid. | 参数不合法 |
| -1153 | User not exist | 用户不存在 |
| -1218 | Only data from the last 180 days can be queried. | 仅支持查询最近 180 天的数据 |
| -1219 | This endpoint is only available to agents. | 当前 API Key 对应账号不是有效代理人 |
查询被邀请人
查询当前代理人直接或间接邀请的用户基础信息，支持按注册时间、UID 或邀请码筛选。
Request Weight
1
Request URL
GET /api/v1/agent/inviteUserList
Parameters
| 参数名称 | 类型 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|---|
| pageIndex | INTEGER | NO | 1 | 页码，从 1 开始 |
| pageSize | INTEGER | NO | 100 | 每页条数，范围 100 到 200 |
| startTime | LONG | NO | 0 | 注册时间筛选开始时间；与 endTime 同时传入时，时间跨度不能超过 30 天 |
| endTime | LONG | NO | 0 | 注册时间筛选结束时间 |
| uid | LONG | NO | 0 | 被邀请用户 UID |
| referralCode | STRING | NO | - | 邀请码 |
Response
data.list[] 字段：
| 字段 | 类型 | 说明 |
|---|---|---|
| uid | long | 被邀请用户 UID |
| ownInviteCode | string | 被邀请用户自己的邀请码；代理人返回，普通直客可能为空 |
| inviteSid | long | 上级 UID |
| invitationCode | string | 注册时填写的上级邀请码 |
| registerTime | long | 注册时间，毫秒时间戳 |
| directInvitation | boolean | true 直接邀请，false 间接邀请 |
| deposit | boolean | true 已入金，false 未入金 |
| balanceVolume | string | 净资产，折算 USDT |
| trade | boolean | true 已交易，false 未交易 |
| kycResult | boolean | true 已通过 KYC，false 未通过 KYC |
| level | integer | 用户等级 |
| spotCommissionRatio | string | 现货返佣比例 |
| contractCommissionRatio | string | 合约返佣比例 |
返佣明细查询
按小时查询被邀请用户的返佣明细。仅支持查询最近 365 天内的数据，单次查询时间跨度不能超过 30 天。
Request Weight
1
Request URL
GET /api/v1/agent/commissionDataList
Parameters
| 参数名称 | 类型 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|---|
| uid | LONG | NO | 0 | 被邀请用户 UID；不传或传 0 表示不按 UID 过滤 |
| pageIndex | INTEGER | NO | 1 | 页码，从 1 开始 |
| pageSize | INTEGER | NO | 100 | 每页条数，范围 100 到 200 |
| startTime | LONG | YES | - | 统计开始时间，毫秒时间戳 |
| endTime | LONG | YES | - | 统计结束时间，毫秒时间戳 |
Response
data.list[] 字段：
| 字段 | 类型 | 说明 |
|---|---|---|
| uid | long | 被邀请用户 UID |
| commissionTime | long | 返佣发放时间 |
| tradingVolume | string | 现货和合约总交易量，折算 USDT |
| commissionVolume | string | 总返佣金额，折算 USDT |
| spotTradingVolume | string | 现货交易量，折算 USDT |
| swapTradingVolume | string | 合约交易量，折算 USDT |
| spotCommissionVolume | string | 现货返佣金额，折算 USDT |
| swapCommissionVolume | string | 合约返佣金额，折算 USDT |
返佣汇总查询
按被邀请用户查询返佣汇总。仅支持查询最近 365 天内的数据，单次查询时间跨度不能超过 30 天。
Request Weight
1
Request URL
GET /api/v1/agent/commissionDataInfo
Parameters
| 参数名称 | 类型 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|---|
| uid | LONG | NO | 0 | 被邀请用户 UID；不传或传 0 表示不按 UID 过滤 |
| pageIndex | INTEGER | NO | 1 | 页码，从 1 开始 |
| pageSize | INTEGER | NO | 100 | 每页条数，范围 100 到 200 |
| startTime | LONG | YES | - | 统计开始时间，毫秒时间戳 |
| endTime | LONG | YES | - | 统计结束时间，毫秒时间戳 |
| referralCode | STRING | NO | - | 被邀请用户的邀请码 |
Response
data.list[] 字段：
| 字段 | 类型 | 说明 |
|---|---|---|
| uid | long | 被邀请用户 UID |
| tradingVolume | string | 现货和合约总交易量，折算 USDT |
| commissionVolume | string | 总返佣金额，折算 USDT |
| spotTradingVolume | string | 现货交易量，折算 USDT |
| swapTradingVolume | string | 合约交易量，折算 USDT |
| spotCommissionVolume | string | 现货返佣金额，折算 USDT |
| swapCommissionVolume | string | 合约返佣金额，折算 USDT |
| fee | string | 总手续费 |
| netFee | string | 净手续费 |
| spotFee | string | 现货手续费 |
| contractFee | string | 合约手续费 |
| spotNetFee | string | 现货净手续费 |
| contractNetFee | string | 合约净手续费 |
查询子代理用户信息
查询子代理用户信息。此接口只能查询子代理，不能查询直客。
Request Weight
1
Request URL
GET /api/v1/agent/inviteRelationCheck
Parameters
| 参数名称 | 类型 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|---|
| uid | LONG | YES | - | 子代理用户 UID |
Response
data 字段：
| 字段 | 类型 | 说明 |
|---|---|---|
| uid | long | 子代理用户 UID |
| inviteSid | long | 上级 UID |
| registerTime | long | 注册时间，毫秒时间戳 |
| directInvitation | boolean | true 直接邀请，false 间接邀请 |
| deposit | boolean | true 已入金，false 未入金 |
| kycResult | boolean | true 已通过 KYC，false 未通过 KYC |
| balanceVolume | string | 净资产，折算 USDT |
| trade | boolean | true 已交易，false 未交易 |
| level | integer | 用户等级 |
| spotCommissionRatio | string | 现货返佣比例 |
| contractCommissionRatio | string | 合约返佣比例 |
入金明细查询
查询被邀请用户的入金明细。仅支持查询最近 90 天内的数据，单次查询时间跨度不能超过 30 天。
Request Weight
1
Request URL
GET /api/v1/agent/depositDetailList
Parameters
| 参数名称 | 类型 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|---|
| uid | LONG | YES | - | 被邀请用户 UID |
| pageIndex | INTEGER | NO | 1 | 页码，从 1 开始 |
| pageSize | INTEGER | NO | 100 | 每页条数，范围 100 到 200 |
| startTime | LONG | YES | - | 查询开始时间，毫秒时间戳 |
| endTime | LONG | YES | - | 查询结束时间，毫秒时间戳 |
Response
data.list[] 字段：
| 字段 | 类型 | 说明 |
|---|---|---|
| uid | long | 被邀请用户 UID |
| directInvitation | boolean | true 直接邀请，false 间接邀请 |
| bizType | integer | 业务类型；1 表示入金 |
| bizTime | long | 入金时间，毫秒时间戳 |
| tokenId | string | 币种 |
| quantity | string | 入金数量 |
查询充值和提币明细
查询指定用户的成功充值和提币记录。startTime 必须在当前时间往前 180 天内，时间范围为 [startTime, endTime)，最大跨度 180 天，倒序返回。
Request Weight
1
Request URL
GET /api/v1/agent/deposit-withdraw/details
Parameters
| 参数名称 | 类型 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|---|
| userId | LONG | YES | - | 查询用户 UID，必须大于 0 |
| startTime | LONG | YES | - | 查询开始时间，毫秒时间戳，包含；不能早于当前时间往前 180 天 |
| endTime | LONG | YES | - | 查询结束时间，毫秒时间戳，不包含 |
| type | STRING | NO | - | 单个出入金类型；不传表示全部 |
| cursor | STRING | NO | - | 下一页游标；首次查询不传 |
| limit | INTEGER | NO | 100 | 每页条数，范围 1 到 100 |
type 可选值：
| 值 | 说明 |
|---|---|
ON_CHAIN_DEPOSIT | 链上充值 |
INTERNAL_DEPOSIT | 站内充值 |
ON_CHAIN_WITHDRAWAL | 链上提币 |
INTERNAL_WITHDRAWAL | 站内提币或转账 |
Response
| 字段 | 类型 | 说明 |
|---|---|---|
| data.list | array | 当前页明细，无数据时为空数组 |
| data.nextCursor | string | 下一页游标，无下一页时为空字符串 |
| data.hasMore | boolean | 是否还有下一页 |
data.list[] 字段：
| 字段 | 类型 | 说明 |
|---|---|---|
| userId | string | 出入金用户 UID |
| remark | string / null | 直客备注；代理人返回 null |
| inviterUserId | string | 邀请人 UID |
| inviteType | string | DIRECT 直属，SUB_AGENT 子代理 |
| type | string | 出入金类型 |
| token | string | 币种 |
| quantity | string | 数量 |
| createdTime | long | 记录时间，毫秒时间戳 |
当 hasMore=true 时，在相同查询条件下将 nextCursor 原样传入下一次请求。
子代理数据查询
查询下级代理或被邀请用户在统计窗口内的业务数据。未传时间时默认查询最近 30 天；仅支持查询最近 90 天内的数据，单次查询时间跨度不能超过 30 天。
Request Weight
1
Request URL
GET /api/v1/agent/querySubAgentData
Parameters
| 参数名称 | 类型 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|---|
| uid | LONG | NO | 0 | 下级代理或被邀请用户 UID；不传或传 0 表示不按 UID 过滤 |
| pageIndex | INTEGER | NO | 1 | 页码，从 1 开始 |
| pageSize | INTEGER | NO | 100 | 每页条数，范围 100 到 200 |
| startTime | LONG | NO | 0 | 查询开始时间，毫秒时间戳 |
| endTime | LONG | NO | 0 | 查询结束时间，毫秒时间戳 |
Response
data.list[] 字段：
| 字段 | 类型 | 说明 |
|---|---|---|
| uid | long | 用户 UID |
| string | 脱敏邮箱 | |
| phone | string | 脱敏手机号 |
| directInvitation | boolean | true 直接邀请，false 间接邀请 |
| newReferees | integer | 查询期间新邀请人数 |
| firstTrade | integer | 首次交易人数 |
| branchDeposits | string | 下级入金金额 |
| branchTrading | integer | 下级交易人数 |
| branchTradingVol | string | 下级交易金额 |
| level | integer | 相对级别 |
| spotCommissionRatio | string | 现货返佣比例 |
| contractCommissionRatio | string | 合约返佣比例 |
| commissionAmount | string | 返佣金额 |
现货订单查询
查询代理体系下用户的现货订单。未传时间时默认查询最近 7 天；仅支持查询最近 180 天内的数据，单次查询时间跨度不能超过 30 天。
Request Weight
1
Request URL
GET /api/v1/agent/spotOrdersList
Parameters
| 参数名称 | 类型 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|---|
| parentAccountId | LONG | YES | - | 母账户 ID；仅按子账户查询时可传 0 |
| subAccountId | LONG | YES | - | 子账户 ID；仅按母账户查询时可传 0 |
| fromId | LONG | NO | 0 | 起始游标 ID |
| endId | LONG | NO | 0 | 结束游标 ID |
| startTime | LONG | NO | 0 | 查询开始时间，毫秒时间戳 |
| endTime | LONG | NO | 0 | 查询结束时间，毫秒时间戳 |
| limit | INTEGER | NO | 100 | 返回条数，范围 1 到 200 |
parentAccountId 与 subAccountId 不能同时为 0。
Response
data 为数组，每个元素包含：
| 字段 | 类型 | 说明 |
|---|---|---|
| orderId | long | 订单 ID |
| userId | long | 用户 ID |
| mark | string | 标记字段 |
| symbolId | string | 币对 ID |
| side | integer | 买卖方向；1 买，2 卖 |
| time | long | 下单时间，毫秒时间戳 |
| orderType | integer | 订单类型；0 限价，2 市价 |
| origQty | string | 原始数量 |
| executedQty | string | 成交数量 |
| executedAmount | string | 成交额，折算 USDT |
| avgPrice | string | 平均成交价 |
| deductedFee | string | 扣除手续费 |
| isAgent | boolean | 是否代理人 |
| childUserId | long | 子用户 ID |
合约订单查询
查询代理体系下用户的合约订单。未传时间时默认查询最近 7 天；仅支持查询最近 180 天内的数据，单次查询时间跨度不能超过 30 天。
Request Weight
1
Request URL
GET /api/v1/agent/futuresOrdersList
Parameters
| 参数名称 | 类型 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|---|
| parentAccountId | LONG | YES | - | 母账户 ID；仅按子账户查询时可传 0 |
| subAccountId | LONG | YES | - | 子账户 ID；仅按母账户查询时可传 0 |
| fromId | LONG | NO | 0 | 起始游标 ID |
| endId | LONG | NO | 0 | 结束游标 ID |
| startTime | LONG | NO | 0 | 查询开始时间，毫秒时间戳 |
| endTime | LONG | NO | 0 | 查询结束时间，毫秒时间戳 |
| limit | INTEGER | NO | 100 | 返回条数，范围 1 到 200 |
parentAccountId 与 subAccountId 不能同时为 0。
Response
data 为数组，每个元素包含：
| 字段 | 类型 | 说明 |
|---|---|---|
| orderId | long | 订单 ID |
| userId | long | 用户 ID |
| vipLevel | string | VIP 等级 |
| mark | string | 标记字段 |
| symbolId | string | 合约币对 ID |
| marginType | string | 保证金模式 |
| time | long | 下单时间，毫秒时间戳 |
| orderSide | string | 订单方向 |
| price | string | 委托价格 |
| origQty | string | 原始数量 |
| executedQty | string | 成交数量 |
| avgPrice | string | 平均成交价 |
| pnl | string | 盈亏 |
| deductedFee | string | 扣除手续费 |
| isAgent | boolean | 是否代理人 |
| feeTokenId | string | 手续费币种 ID |
| childUserId | long | 子用户 ID |
合约持仓查询
查询代理体系下用户的合约持仓。
Request Weight
1
Request URL
GET /api/v1/agent/futuresPositionsList
Parameters
| 参数名称 | 类型 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|---|
| parentAccountId | LONG | YES | - | 母账户 ID；仅按子账户查询时可传 0 |
| subAccountId | LONG | YES | - | 子账户 ID；仅按母账户查询时可传 0 |
| fromId | LONG | NO | 0 | 起始游标 ID |
| endId | LONG | NO | 0 | 结束游标 ID |
| limit | INTEGER | NO | 100 | 返回条数，范围 1 到 200 |
parentAccountId 与 subAccountId 不能同时为 0。
Response
data 为数组，每个元素包含：
| 字段 | 类型 | 说明 |
|---|---|---|
| positionId | long | 持仓 ID |
| userId | long | 用户 ID |
| vipLevel | string | VIP 等级 |
| mark | string | 标记字段 |
| symbolId | string | 合约币对 ID |
| marginType | string | 保证金模式 |
| leverage | string | 杠杆倍数 |
| isLong | integer | 是否多头；1 多头，0 空头 |
| total | string | 总持仓量 |
| avgPrice | string | 平均开仓价 |
| margin | string | 保证金 |
| riskRate | string | 风险率 |
| unrealisedPnl | string | 未实现盈亏 |
| profitRate | string | 利润率 |
| liquidationPrice | string | 强平价格 |
| childUserId | long | 子用户 ID |
被邀请人返佣信息
查询指定被邀请用户的返佣关系和累计返佣信息。
Request Weight
1
Request URL
GET /api/v1/agent/invite-commission-detail
Parameters
| 参数名称 | 类型 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|---|
| uid | LONG | YES | - | 被邀请用户 UID |
| startTime | LONG | NO | 0 | 查询开始时间，毫秒时间戳 |
| endTime | LONG | NO | 0 | 查询结束时间，毫秒时间戳 |
Response
data 字段：
| 字段 | 类型 | 说明 |
|---|---|---|
| uid | long | 被邀请用户 UID |
| joinTime | string | 返佣关系建立时间，毫秒时间戳字符串 |
| inviteeRebateRate | string | 通过该用户获得的返佣比例，小数形式，例如 0.01 表示 1% |
| totalCommission | string | 累计返佣数量，可能包含多个币种 |
| firstTradeTime | string | 首次交易时间，毫秒时间戳字符串；未交易时为空字符串 |
| level | string | 用户等级，例如 Lv1 |
| volMonth | string | 当月累计交易量，单位 USDT |
| accFee | string | 累计交易手续费 |
| region | string | 国家或地区代码 |
| affiliateCode | string | 邀请码 |
申请交易明细导出
申请生成代理人交易明细下载文件。该接口会创建导出任务，不支持只读 API Key。默认导出最近 7 天数据，最大查询跨度 180 天，最多导出 10000 条记录。
Request Weight
1
Request URL
GET /api/v1/agent/user/export
Parameters
| 参数名称 | 类型 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|---|
| beginTime | STRING | NO | 最近 7 天开始日期 | 起始日期，格式 YYYYMMdd，例如 20210623 |
| endTime | STRING | NO | 当前日期 | 结束日期，格式 YYYYMMdd |
| uid | LONG | NO | 0 | 交易用户 UID |
Response
| 字段 | 类型 | 说明 |
|---|---|---|
| data | boolean | true 导出任务已提交，false 导出失败 |
查询导出任务列表
查询已申请的交易明细导出任务。下载任务通常 7 天内有效。
Request Weight
1
Request URL
GET /api/v1/agent/export-list
Parameters
| 参数名称 | 类型 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|---|
| limit | INTEGER | NO | 50 | 返回条数，范围 1 到 200 |
| fromId | LONG | NO | 0 | 起始游标 ID |
| endId | LONG | NO | 0 | 结束游标 ID |
| type | INTEGER | NO | 0 | 导出类型；0 表示交易明细 |
Response
data 为数组，每个元素包含：
| 字段 | 类型 | 说明 |
|---|---|---|
| downToken | string | 下载任务唯一标识 |
| applyTime | long | 申请时间，毫秒时间戳 |
| filterStartTime | long | 导出筛选开始时间 |
| filterEndTime | long | 导出筛选结束时间 |
| status | integer | 任务状态；0 申请中，1 已完成，2 已取消 |
| type | integer | 导出类型；0 表示交易明细 |
获取导出下载链接
获取已完成导出任务的下载链接。下载链接有效期为 60 秒，过期后可重新调用本接口获取。
Request Weight
1
Request URL
GET /api/v1/agent/export-url
Parameters
| 参数名称 | 类型 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|---|
| downToken | STRING | NO | - | 下载任务唯一标识，推荐使用该参数 |
| token | STRING | NO | - | 兼容参数；未传 downToken 时使用 |
downToken 与 token 至少传一个。
Response
| 字段 | 类型 | 说明 |
|---|---|---|
| data | string | 下载链接 |