核心概念
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 流程內部收取，不走你的帳戶。