API 參考

Base URL：https://api.allswap.io。所有請求走 HTTPS + JSON。所有金額都是最小單位的字串（如 wei、satoshi、USDT 6 位精度 → 乘以 10⁶）。所有時間戳為 ISO 8601 UTC。

請求標頭見身份驗證，錯誤回應格式見錯誤碼。

`GET /v1/tokens`

列出所有支援的鏈上所有可路由的代幣。

查詢參數

Field	Type	Description
`chain`選填	`string`	按鏈 slug 過濾，例如 ethereum、tron、solana。
`search`選填	`string`	按 symbol 或 name 做模糊比對。

curl https://api.allswap.io/v1/tokens?chain=ethereum \
  -H "X-Key-Id: ak_live_yourapp" \
  -H "Authorization: Bearer sk_live_..."

`POST /v1/quote`

取得一份不具約束力的價格預覽。回傳的 quoteId 是後續提交 POST /v1/swap 用的標識。報價約 30 秒過期。

請求體

Field	Type	Description
`from`必填	`string (CAIP-19)`	來源資產 ID，例如 eip155:1/erc20:0xdac1...
`to`必填	`string (CAIP-19)`	目標資產 ID。
`amount`必填	`string (integer)`	輸入金額，以 `from` 的最小單位表示。
`sender`必填	`string`	使用者在來源鏈上的地址。僅用於路由 —— 報價階段不需要簽名。
`recipient`必填	`string`	使用者在目標鏈上的地址。
`slippageBps`選填	`integer`	最大可接受滑點，單位 bps。預設 50。

curl -X POST https://api.allswap.io/v1/quote \
  -H "X-Key-Id: ak_live_yourapp" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "eip155:1/erc20:0xdac17f958d2ee523a2206206994597c13d831ec7",
    "to":   "tron:mainnet/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "amount": "1000000000",
    "sender":    "0xYourUserEvmAddress",
    "recipient": "TYourUserTronAddress"
  }'

`POST /v1/swap`

提交一筆報價。我們會產生一次性存款地址 —— 使用者向該地址轉入資金後，swap 立即開始執行。

請求體

Field	Type	Description
`quoteId`必填	`string`	上一次 /v1/quote 呼叫回傳的 ID，不能過期。
`webhookUrl`選填	`string (URL)`	僅對本筆 swap 覆寫控制台級別的 webhook 地址。
`metadata`選填	`object`	自由 JSON ≤ 1 KB。會在 /v1/swap/:id 和 webhook 中原樣回傳。可用來串聯自家的 user id / order id。

curl -X POST https://api.allswap.io/v1/swap \
  -H "X-Key-Id: ak_live_yourapp" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "qt_01HW9...",
    "metadata": { "orderId": "ord_42" }
  }'

`GET /v1/swap/{id}`

查詢 swap 目前狀態。建議每 10–15 秒輪詢一次，或者更好 —— 在控制台訂閱 webhook。

curl https://api.allswap.io/v1/swap/sw_01HW9... \
  -H "X-Key-Id: ak_live_yourapp" \
  -H "Authorization: Bearer sk_live_..."

狀態列舉： PENDING_DEPOSIT → KNOWN_DEPOSIT_TX → PROCESSING → SUCCESS；終態分支為 REFUNDED 和 FAILED。詳見概念 → 交易。

`GET /v1/usage/me`

查詢目前金鑰的配額使用情況。可以在你自己的管理介面展示剩餘額度，免去讓團隊打開我們控制台的麻煩。

curl https://api.allswap.io/v1/usage/me \
  -H "X-Key-Id: ak_live_yourapp" \
  -H "Authorization: Bearer sk_live_..."

Webhook

在控制台設定 webhook URL（或在建立 swap 時透過 webhookUrl 欄位單獨指定）。每次 swap 狀態變化，我們都會 POST 一份 JSON 信封：

{
  "type":      "swap.status_changed",
  "swapId":    "sw_01HW9...",
  "status":    "SUCCESS",
  "occurredAt":"2026-06-22T10:03:58Z",
  "metadata":  { "orderId": "ord_42" }
}

每條 webhook 都帶 X-Allswap-Signature header —— 用你的 webhook 密鑰對原始 body 做的 HMAC-SHA256。驗證後再信任負載。Webhook 是 at-least-once 投遞；讓處理器對 swapId + status 冪等。