WaaS 开放接口文档

本文档面向交易所（租户）的后端工程师，说明如何通过 B 端开放接口（/v1）为你的用户托管多链充值地址、接收充值、发起提现与站内转账，并通过回调（Webhook）同步状态。

业务介绍：FableWallet 官网。公开接入文档地址为 https://docs.fablewallet.top/。

机器可读规范

完整的 OpenAPI 3.1 描述：openapi.yaml（可导入 Postman、Apifox、Swagger UI 或代码生成器）。

能力一览

能力	说明	文档
用户	以交易所自己的用户 ID（`customerRefId`）登记用户；邮箱可选；冻结/解冻	用户
充值地址	一次调用：自动创建用户与默认钱包并返回充值地址；所有 EVM 链共用同一地址	用户
钱包	每个用户在每个链族（EVM / TRON / BTC / SOL）下可有多个钱包（默认上限 10）	钱包与地址
资产与网络	查询可用网络、资产精度、最小充值/提现额、充值费与提现费；地址校验	资产与网络
充值	链上入账、确认/最终性、充值手续费在入账时扣除	充值
提现 / 站内转账	一个接口：外部地址走链上；本租户内的地址或用户自动站内结算（不上链、无网络费）	提现与站内转账
回调	Ed25519 签名的事件推送，失败自动重试，可查询投递记录、手动重发	回调
余额	按钱包或按用户汇总的可用 / 冻结余额	钱包与地址、用户

对接流程

开通：平台为你开通租户，并给你租户后台（控制台）的管理员账号。
创建 API Key：在租户后台 API Keys 页面登记 Ed25519 公钥（私钥只在你方生成和保存），可设置 IP 白名单与每秒请求上限。见快速开始。
实现签名：每个请求带 X-API-Key 与 Authorization: Bearer <JWT>，JWT 用你的私钥签名。见认证与签名。
注册回调地址：POST /v1/webhooks，并用平台公钥验证每条回调。见回调。
获取充值地址：POST /v1/users/{customerRefId}/deposit_address，展示给你的用户。
处理充值回调：收到 TRANSACTION_STATUS_UPDATED 且 data.kind = DEPOSIT、data.status = COMPLETED 时，按 data.netAmountRaw 给用户记账。
发起提现：POST /v1/transactions，用 externalTxId 关联你方提现单并保证幂等；通过回调或查询跟踪到终态。
对账：定期用 GET /v1/transactions 按时间窗口拉取流水，与回调结果互相校验。

text

交易所后端                                   WaaS
   │  POST /v1/users/{ref}/deposit_address     │
   │──────────────────────────────────────────▶│ 建用户 + 默认钱包 + 地址
   │◀──────────────────────────── address ─────│
   │                                           │  链上到账、确认、入账（扣充值费）
   │◀───── Webhook TRANSACTION_STATUS_UPDATED ─│  data.kind=DEPOSIT, status=COMPLETED
   │  POST /v1/transactions (externalTxId)     │
   │──────────────────────────────────────────▶│ 冻结余额 → 风控 → 签名 → 广播 → 确认
   │◀───── Webhook TRANSACTION_STATUS_UPDATED ─│  data.kind=WITHDRAWAL, status=COMPLETED

环境

项目	值
Base URL	`https://api.example.com`（占位，实际地址由平台在开通时提供）
路径前缀	所有 B 端接口都在 `/v1` 下，例如 `https://api.example.com/v1/supported_assets`
协议	HTTPS；请求与响应均为 `application/json; charset=utf-8`
请求体上限	256 KiB（超出返回错误码 `BAD_REQUEST`，见通用约定）
单请求超时	服务端 30 秒

测试环境与生产环境的 Base URL 及租户账号由平台分别提供；某个网络是否为测试网可从 GET /v1/networks 的 isTestnet 字段判断。

预生产入口为 https://api.staging.fablewallet.top，文档站为 https://docs.staging.fablewallet.top。当前 Signer 关闭，未配置链网络，暂用于接口认证、文档和前端联调；充值地址申请、签名与充提须等保管人初始化和测试网配置完成。租户/API Key 由平台单独开通，不能使用本地开发账号；C 端注册暂不可用。

术语

术语	含义
租户（tenant）	接入本平台的交易所。每个 API Key 属于一个租户，所有数据按租户隔离。
`customerRefId`	交易所侧的用户 ID，由你方定义，1–128 个字符，在租户内唯一，必填。B 端接口以它定位用户。建议使用不含 `/`、`?`、`#`、空格的稳定 ID；放在 URL 路径中时必须做 URL 编码。
`email`	用户邮箱，可选；若提供，在租户内必须唯一（冲突返回 `409 EMAIL_TAKEN`）。
`uid`	平台为用户分配的 8 位数字字符串 ID（租户内唯一）。站内转账可用 `uid` 或 `customerRefId` 指定收款人。
链族（`chainFamily`）	`EVM`、`TRON`、`BTC`、`SOL`。钱包属于一个链族。
钱包（wallet）	用户在某个链族下的账户，有唯一 `id`（UUID）和一个充值地址；余额按资产记账。
默认钱包	用户在每个链族下的第一个钱包自动成为默认钱包；一次调用获取充值地址、按用户站内转账都使用默认钱包。
地址（`address`）	钱包的充值地址。同一 EVM 钱包在所有 EVM 网络上地址相同（如 Ethereum 与 BNB Chain 共用）。
`networkKey`	网络标识，例如 `ethereum`、`tron`（示例，以 `GET /v1/networks` 返回为准）。
`assetId`	资产标识，一个资产属于一个网络，例如 `USDT_ERC20`（示例，以 `GET /v1/supported_assets` 返回为准）。
raw / 最小单位	所有金额字段（以 `Raw` 结尾）都是最小单位的十进制整数字符串，例如 USDT（6 位精度）的 `"1500000"` = 1.5 USDT。精度见资产的 `decimals`。
`externalTxId`	你方为一笔提现/转账生成的唯一 ID（1–128 字符），同时作为幂等键。
站内结算（`OFF_CHAIN`）	收款方是本租户的钱包时，直接在账本内划转，不上链、无网络费。
链上结算（`ON_CHAIN`）	收款方为外部地址（含其他租户的地址）时，平台签名并广播链上交易。

WaaS 开放接口文档 ​

能力一览 ​

对接流程 ​

环境 ​

术语 ​

WaaS 开放接口文档

能力一览

对接流程

环境

术语