FableWallet 开放接口文档

Appearance

钱包与地址 ​

每个用户在每个链族（EVM、TRON、BTC、SOL）下可以有多个钱包，默认最多 10 个（按链族分别计数，租户可下调）。每个钱包有一个充值地址；同一 EVM 钱包在所有已开通的 EVM 网络上使用同一地址。余额按钱包 + 资产记账。

用户在某链族下的第一个钱包自动成为默认钱包。一次调用获取充值地址 和按用户站内转账（END_USER）都使用默认钱包。大多数交易所只需要默认钱包，不必直接调用本页的创建接口。

钱包对象 ​

字段类型说明
idstring (UUID)钱包 ID
tenantIdstring (UUID)所属租户
userIdstring (UUID)平台内部用户 ID
chainFamilystringEVM / TRON / BTC / SOL
namestring钱包名称（最多 40 字符），默认为 "<链族> <序号>"，如 "EVM 1"
seqinteger该用户在该链族下的钱包序号，从 1 开始
isDefaultboolean是否为该链族的默认钱包
statusstring见下表
addressstring | null充值地址；分配完成前为 null
createdAtstring创建时间（RFC 3339）
钱包状态含义
PROVISIONING创建中，地址分配后自动变为 ACTIVE（通常数秒）
ACTIVE正常
HIDDEN被用户在 C 端隐藏；仍可接收本人其他钱包的转账
FROZEN已冻结：不能转出；到账的充值不会自动入账，转人工处理
CLOSED已关闭

创建钱包 ​

http
POST /v1/wallets

为用户在指定链族下新建一个钱包。若 customerRefId 对应的用户不存在，会先创建用户（不带邮箱）。钱包创建后异步分配地址，分配完成时推送 WALLET_CREATED 回调。

请求头

头必填说明
X-API-Key、Authorization是见 认证与签名
Idempotency-Key是幂等键，1–128 字符 [A-Za-z0-9_-:.]，见 幂等

请求体

字段类型必填说明
customerRefIdstring是交易所侧用户 ID（1–128 字符）
chainFamilystring是EVM / TRON / BTC / SOL
namestring否钱包名称，超过 40 字符会被截断
json
{ "customerRefId": "u-10001", "chainFamily": "TRON", "name": "trading" }

响应 202 Accepted：钱包对象，此时 status = "PROVISIONING"、address = null。

json
{
  "id": "0192a4c2-0c11-7f03-8a77-0b1c2d3e4f50",
  "tenantId": "0191f0aa-1b2c-7d3e-8f40-5a6b7c8d9e0f",
  "userId": "0192a4c1-7a3e-7c51-9a64-2f0d3b8e4a10",
  "chainFamily": "TRON",
  "name": "trading",
  "seq": 1,
  "isDefault": true,
  "status": "PROVISIONING",
  "address": null,
  "createdAt": "2026-10-03T05:01:12.481902Z"
}

之后用 GET /v1/wallets/{id} 或 GET /v1/wallets/{id}/addresses 轮询，或等待 WALLET_CREATED 回调。

常见错误

HTTPcode场景
422BAD_REQUEST缺少或非法 Idempotency-Key；customerRefId 长度不对；chainFamily 取值非法
403FORBIDDEN用户已冻结（user is not active）
409IDEMPOTENCY_CONFLICT同一幂等键对应不同请求体，或上一次请求仍在处理
422NETWORK_DISABLED本租户在该链族下没有可开新钱包的网络（<FAMILY> wallets are not open）
422WALLET_LIMIT_REACHED该用户在该链族下钱包数已达上限（at most 10 EVM wallets per user）
429RATE_LIMITED该用户 24 小时内新建钱包过多（默认 5 个）

钱包列表 ​

http
GET /v1/wallets?customerRefId=u-10001&limit=50&before=<nextBefore>

查询参数

参数类型必填说明
customerRefIdstring否只返回该用户的钱包
limitinteger否1–200，默认 50
beforestring (UUID)否上一页的 nextBefore

响应 200 OK。列表项与钱包对象相同，但不含 tenantId，另含 customerRefId：

json
{
  "items": [
    {
      "id": "0192a4c1-8b10-7e22-b3a1-6f1e2d3c4b5a",
      "userId": "0192a4c1-7a3e-7c51-9a64-2f0d3b8e4a10",
      "customerRefId": "u-10001",
      "chainFamily": "EVM",
      "name": "EVM 1",
      "seq": 1,
      "isDefault": true,
      "status": "ACTIVE",
      "address": "0x8ba1f109551bd432803012645ac136ddd64dba72",
      "createdAt": "2026-10-03T04:55:50.002311Z"
    }
  ],
  "nextBefore": null
}

查询钱包 ​

http
GET /v1/wallets/{id}

响应 200 OK：钱包对象。

常见错误：404 NOT_FOUND（wallet not found，包括钱包不属于本租户）。

查询钱包余额 ​

http
GET /v1/wallets/{id}/assets

响应 200 OK：数组，每个有过记账的资产一项。

json
[
  { "assetId": "ETH", "available": "250000000000000000", "frozen": "0" },
  { "assetId": "USDT_ERC20", "available": "75000000", "frozen": "10000000" }
]
字段说明
assetId资产 ID
available可用余额（最小单位字符串）。注意本接口字段名不带 Raw 后缀
frozen冻结余额（最小单位字符串）

常见错误：404 NOT_FOUND。

查询钱包充值地址 ​

http
GET /v1/wallets/{id}/addresses

按网络列出该钱包的充值地址，以及每个网络上可充值的资产、最小充值额与充值手续费。只包含钱包所属链族中、本租户已开通且允许充值的网络。

响应 200 OK

json
[
  {
    "walletId": "0192a4c1-8b10-7e22-b3a1-6f1e2d3c4b5a",
    "networkKey": "ethereum",
    "networkName": "Ethereum",
    "address": "0x8ba1f109551bd432803012645ac136ddd64dba72",
    "watchStatus": "ACTIVE",
    "confirmations": { "mode": "confirmations", "n": 12 },
    "supportedAssets": [
      {
        "assetId": "USDT_ERC20",
        "symbol": "USDT",
        "name": "Tether USD",
        "decimals": 6,
        "minDepositRaw": "1000000",
        "depositFeeRaw": "500000",
        "depositPaused": false,
        "iconUrl": null
      }
    ]
  }
]
字段说明
address该网络上的充值地址。仅当钱包为 ACTIVE 且该网络的监听状态为 ACTIVE / DEGRADED 时返回，否则为 null（请勿展示给用户）
watchStatus地址在该网络上的监听状态：ALLOCATED、REGISTERING、ACTIVE、DEGRADED（监听降级，仍会入账但可能延迟）、FROZEN；未注册时为 null
confirmations该网络的入账条件：{"mode":"confirmations","n":N}（N 个确认）、{"mode":"finalized"} 或 {"mode":"solidified"}（链上最终确定）
supportedAssets[].minDepositRaw最小充值额；低于此金额的充值不会自动入账
supportedAssets[].depositFeeRaw当前充值手续费，入账时从充值金额中扣除
supportedAssets[].depositPausedtrue 表示该资产暂停充值：到账后不会自动入账，转人工处理

常见错误：404 NOT_FOUND。