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 为准。