代理人接口

代理人 OpenAPI 使用 /api/v1/agent 前缀。所有接口都需要 API Key 签名，适用于已开通代理人能力的账户。

• 所有接口均为 GET，业务参数通过 query string 传递。
• 所有接口都需要签名，公共签名规则请参考基础信息。
• 所有接口限频均为每 1 秒最多 5 次请求，接口权重为 1。
• 除特别说明外，时间字段均为毫秒级 UNIX 时间戳。
• 分页接口的 pageIndex 默认 1，pageSize 默认 100，取值范围为 100 到 200。

公共签名参数

参数名称	类型	是否必需	描述
recvWindow	LONG	NO	请求有效时间窗口，单位毫秒；未传时默认 5000
timestamp	LONG	YES	请求时间戳，单位毫秒
signature	STRING	YES	使用 API Secret 对请求参数计算得到的 HMAC SHA256 签名

通用响应结构

成功响应统一返回：

{
  "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	用户不存在

---

查询被邀请人

查询当前代理人直接或间接邀请的用户基础信息，支持按注册时间、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	合约净手续费

---

邀请关系校验

校验指定 UID 是否与当前代理人存在邀请关系，并返回该用户的基础代理信息。

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	入金数量

---

子代理数据查询

查询下级代理或被邀请用户在统计窗口内的业务数据。未传时间时默认查询最近 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
email	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	下载链接