账户能力

HoldFi 为开放应用配置一个关联账户。第三方可以查询该账户的 USDT 可用余额、充值地址，以及指定链上交易的充值确认结果。

第三方平台在 HoldFi App 中注册账号,由 HoldFi 在接入阶段配置关联账户，第三方请求中无需传入 HoldFi 用户 ID 或账户 ID。

1. 查询关联账户信息

类型：HoldFi 实现。
调用方向：第三方调用 HoldFi。
API path：/openapi/v1/accounts/info。

1.1 业务请求

payload 解密后的业务请求固定为空对象：

{}

该接口不接收其他业务字段。

1.2 业务响应

data 解密后的成功响应：

{
  "platform": "partner.demo",
  "settlement_token": "USDT",
  "usdt_balance": "1000.5",
  "recharge_addresses": [
    {
      "chain": "BSC",
      "address": "0x1234567890abcdef1234567890abcdef12345678"
    },
    {
      "chain": "TRON",
      "address": "TExampleDepositAddress1234567890123"
    }
  ]
}

字段	类型	说明
platform	String	当前开放应用的平台标识
settlement_token	String	结算资产，当前固定为 USDT
usdt_balance	String	关联账户当前可用 USDT 余额
recharge_addresses	Array	当前支持的 USDT 充值地址列表，可能为空
recharge_addresses[].chain	String	公链常量，当前支持 BSC、TRON
recharge_addresses[].address	String	关联账户在对应公链上的专属充值地址

1.3 业务说明

1. usdt_balance 为普通十进制字符串；余额为零时返回 "0"。
2. recharge_addresses 只返回当前接入环境已启用的 USDT 充值网络。
3. 同一关联账户在同一公链上使用固定的专属充值地址。
4. 如关联账户暂不可用，接口返回 403004。

2. 查询充值确认结果

类型：HoldFi 实现。
调用方向：第三方调用 HoldFi。
API path：/openapi/v1/accounts/recharge/query。

第三方可根据公链和交易哈希查询一笔 USDT 充值在 HoldFi 的处理结果。接口可能汇总同一交易中的多条有效 Transfer 记录。

2.1 业务请求

{
  "chain": "BSC",
  "tx_hash": "0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

字段	必填	类型	说明
chain	是	String	公链常量，当前支持 BSC、TRON
tx_hash	是	String	链上交易哈希

请求只允许以上两个字段。必填字段缺失返回 400002；字段类型或格式错误返回 400001；公链不支持返回 400004。

2.2 已确认响应

{
  "chain": "BSC",
  "tx_hash": "0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "status": "CONFIRMED",
  "token": "USDT",
  "amount": "100.5",
  "credited_amount": "100.5",
  "transfer_count": 1,
  "credited": true,
  "credited_timestamp": 1787824800000
}

2.3 暂未查询到记录

{
  "chain": "BSC",
  "tx_hash": "0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "status": "NOT_FOUND",
  "token": null,
  "amount": null,
  "credited_amount": null,
  "transfer_count": 0,
  "credited": false,
  "credited_timestamp": null
}

2.4 响应字段

字段	类型	说明
chain	String	请求使用的公链常量
tx_hash	String	请求使用的交易哈希
status	String	NOT_FOUND、CONFIRMED 或 FAILED
token	String/null	充值资产；未查询到记录时为 null
amount	String/null	当前交易转入关联账户的有效总额
credited_amount	String/null	当前交易已经实际入账的总额
transfer_count	Integer	本次结果包含的有效 Transfer 数量
credited	Boolean	是否至少有一条记录已经入账
credited_timestamp	Integer/null	最后一条成功入账记录的时间，Unix 毫秒时间戳

2.5 状态说明

status	说明	接入方处理建议
NOT_FOUND	暂未查询到当前关联账户的对应充值记录	间隔一段时间后重试
CONFIRMED	至少有一条有效转入已经入账	使用 credited_amount 作为已入账金额
FAILED	已查询到对应转入记录，但尚无成功入账记录	暂停自动确认并联系 HoldFi 核查

NOT_FOUND 可能表示交易尚未被 HoldFi 处理，不表示链上交易一定不存在。为保护账户数据，其他账户的同一交易也会返回 NOT_FOUND。