核心概念
Allswap API 里有 4 个反复出现的名词：路由 (route) 是穿越流动性的路径，报价 (quote) 是该路径上的价格预览，交易 (swap) 是已提交的动作，费用 (fees) 是成本结构。这一页是接口背后的心智模型。
路由
一条路由是把 A 链上的源资产搬到 B 链上的目标资产的某种方式。我们对接了上游多条聚合路由 —— 内部分别记作 route_A、route_B 等 —— 每次报价挑最优的一条。
从你的视角看，路由选择是不透明的：你发起报价、拿到最优 amount_out 加上一个字符串标识。除非你想记日志，否则不需要关心走了哪条。
为什么屏蔽细节： 上游路由一直在变。报价模型在变、字段在变、新路由上线旧路由被弃用。我们把这些全吸收在稳定的对外契约后面，让你的集成不需要每季度返工。
报价
报价是一份 不具约束力 的价格预览。它告诉你此刻这笔输入在目标链上能拿到多少。报价的特点：
- 约 30 秒过期。 行情在动；我们不接受过期价格。
- 免费。 报价不收费，只占用你当前档位的
quotes/month配额，不占用任何 swap 配额。 - 带
quoteId。 这是你后续提交POST /v1/swap时要传的标识。过期后 quoteId 失效，需要重新报价。
在 swap 确认页上，建议每 ~10 秒刷新一次报价。我们按密钥限速，但 10 秒刷新在任何档位都远低于限额。
交易
一笔 swap 就是已提交的动作 —— 你拿一个有效的 quoteId 调 POST /v1/swap，我们就会生成一次性存款地址并开始监听资金。这笔 swap 在以下状态机里流转：
PENDING_DEPOSIT→KNOWN_DEPOSIT_TX→PROCESSING→SUCCESS
终态分支：REFUNDEDFAILED
你可能遇到的状态：
PENDING_DEPOSIT—— 存款地址已生效，等待资金到达。有expiresAt，过期自动取消。KNOWN_DEPOSIT_TX—— 我们在 mempool 里看到了存款交易，等待确认。PROCESSING—— 存款已确认，路由执行中。多数 swap 从这一步算起 ~3 分钟内结算。SUCCESS—— 目标链资金已交付，含settlementTxHash。REFUNDED—— 中途出现问题，我们已退回存款，含refundTxHash。FAILED—— 收到存款但无法结算也无法自动退款。极少发生；请带上 swapId 联系技术支持。
可以选择每 10–15 秒轮询 GET /v1/swap/:id，或者在控制台注册 webhook URL。Webhook 是 at-least-once 投递 —— 把处理逻辑写成对 swapId 幂等。
费用
报价响应把成本拆成两块：
fee.platformBps—— 平台费率，按输入金额的 bps 收取。已经从amount_out里扣过，不会另外加收。默认 10 bps (0.10%)，Enterprise 档可协商。fee.networkUsd—— gas + 结算成本，折算成美元用于展示。从流动性中支付，不会额外加到用户钱包上。
我们不做的事： 我们绝不按笔向你收费。月度账单只包含档位费用本身。平台 bps 是从 swap 流程内部收取，不走你的账户。