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 幂等。