API 參考

Base URL：https://api.allswap.io。Direct API 目前面向已審核的 Partner 整合；消費者官網使用同一套 quote/order 流程，但透過 Allswap 同源後端完成。所有金額都是最小單位字串，時間戳為 ISO 8601 UTC。

金鑰處理見身份驗證，錯誤與重試見錯誤碼。

`GET /v1/assets`

列出支援鏈上的可路由資產。回傳的 CAIP-19 asset id 用作 originAsset 和 destinationAsset。

查詢參數

Field	Type	Description
`chain`選填	`string`	可選短鏈 key，例如 eth、tron、sol、near。
`search`選填	`string`	可選，按 symbol 或 name 做文字比對。

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

`POST /v1/quote`

取得一份不具約束力的路由預覽。只看價格時傳 dry: true；回應會回傳 provider 候選和 best，不會建立訂單。

請求體

Field	Type	Description
`originAsset`必填	`string (CAIP-19)`	來源資產 ID，來自 /v1/assets。
`destinationAsset`必填	`string (CAIP-19)`	目標資產 ID，來自 /v1/assets。
`amount`必填	`string (integer)`	輸入金額，以來源資產最小單位表示。
`swapType`選填	`EXACT_INPUT \| EXACT_OUTPUT`	預設 EXACT_INPUT。
`slippageToleranceBps`選填	`integer`	最大滑點，單位 bps。不傳則使用 provider 預設值。
`sender`選填	`string`	來源鏈付款地址。真實下單必填；dry quote 可用佔位地址。
`recipient`選填	`string`	目標鏈收款地址。真實下單必填；dry quote 可用佔位地址。
`dry`選填	`boolean`	true 只回傳預覽；false 合併報價和訂單建立。

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 '{
    "originAsset": "eip155:1/erc20:0xdac17f958d2ee523a2206206994597c13d831ec7",
    "destinationAsset": "tron:mainnet/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "amount": "1000000000",
    "swapType": "EXACT_INPUT",
    "slippageToleranceBps": 80,
    "sender": "0xYourSourceAddress",
    "recipient": "TYourDestinationAddress",
    "dry": true
  }'

`POST /v1/order`

使用者接受預覽後建立存款地址訂單。使用者向 depositAddress 轉帳；偵測到入金後，Allswap 執行路由和結算。

請求體

Field	Type	Description
`originAsset`必填	`string (CAIP-19)`	與已接受報價一致的來源資產。
`destinationAsset`必填	`string (CAIP-19)`	與已接受報價一致的目標資產。
`amount`必填	`string (integer)`	精確輸入金額，最小單位字串。
`sender`必填	`string`	會發起入金的來源鏈地址。
`recipient`必填	`string`	接收結算資金的目標鏈地址。
`refundTo`選填	`string`	來源鏈退款地址。不傳時 provider 可能使用 sender。
`providerId`必填	`route_A \| route_B`	使用 dry quote 回應中選定的 provider；做路由比較時通常提交已選定的 provider。

curl -X POST https://api.allswap.io/v1/order \
  -H "X-Key-Id: ak_live_yourapp" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "originAsset": "eip155:1/erc20:0xdac17f958d2ee523a2206206994597c13d831ec7",
    "destinationAsset": "tron:mainnet/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "amount": "1000000000",
    "swapType": "EXACT_INPUT",
    "slippageToleranceBps": 80,
    "sender": "0xYourSourceAddress",
    "recipient": "TYourDestinationAddress",
    "refundTo": "0xYourRefundAddress",
    "providerId": "route_A"
  }'

`GET /v1/order/{id}`

查詢訂單目前狀態。建議每 10-15 秒輪詢到終態；已開通 webhook 的 Partner 帳號也可消費狀態推送。

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

狀態列舉： PENDING、PROCESSING、SUCCESS、REFUNDED、FAILED、UNKNOWN。詳見概念 → 訂單。

`POST /v1/order/{id}/deposit`

可選：提交使用者的入金交易哈希，加快 provider 側狀態追蹤。適合使用者在你的 UI 中完成轉帳廣播後呼叫。

請求體

Field	Type	Description
`txHash`必填	`string`	來源鏈入金交易哈希。
`nearSenderAccount`選填	`string`	僅部分 NEAR 來源鏈入金需要。

curl -X POST https://api.allswap.io/v1/order/ord_01HW9.../deposit \
  -H "X-Key-Id: ak_live_yourapp" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "txHash": "0xabc..."
  }'

`POST /v1/rates`

無需使用者地址，即可把一個來源資產批量預覽到最多 50 個目標資產。適合落地頁、代幣選擇器、伺服器端渲染匯率預覽。

請求體

Field	Type	Description
`from`必填	`string (CAIP-19)`	來源資產 ID。
`amount`必填	`string (integer)`	輸入金額，最小單位字串。
`targets`必填	`string[] (CAIP-19)`	1 到 50 個目標資產 ID。
`swapType`選填	`EXACT_INPUT \| EXACT_OUTPUT`	預設 EXACT_INPUT。

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

Webhook

Partner webhook 使用 order.status_changed 事件。按 at-least-once 投遞處理，並用 orderId 冪等更新你的記錄。

{
  "version": "1",
  "id": "evt_01HW9...",
  "type": "order.status_changed",
  "orderId": "ord_01HW9...",
  "providerId": "route_A",
  "status": "SUCCESS",
  "previousStatus": "PROCESSING",
  "inTxHashes": ["0xabc..."],
  "outTxHashes": ["TXYZ..."],
  "occurredAt": "2026-07-27T10:03:58Z"
}

信任負載前先驗證簽名。建議保存 raw event 便於支援排查，但使用者可見狀態應以歸一化後的 order status 為準。