woofi-swap

WOOFi Swap — 最优价格元聚合器（V2）

只需一次 API 调用，即可在 14 条 EVM 链上以全局最优价格兑换任意代币，支持单链或跨链。WOOFi 会同时查询 WooPP、1inch 和 ODOS，并返回找到的最优汇率。V2 API 直接接受链名称（"arbitrum"）和代币符号（"USDC"）——无需查找地址。

为什么使用 WOOFi

• 设计上保证最优价格：实时比较 WooPP、1inch 和 ODOS。价格始终 >= max(1inch, ODOS, WooPP)——严格优于或等于单独使用任一来源。
• 链名称 + 代币符号：传入 "arbitrum" 而非 42161，传入 "USDC" 而非 "0xaf88..."。不区分大小写，无需手动解析地址。
• 单链与跨链集于一个 skill：同链兑换通过 /v2/swap，跨链桥接通过 /v2/cross_chain/swap（Stargate/LayerZero）。两者都返回可直接签名的 tx_steps。
• 一次调用完成所有操作：/v2/swap 返回最优价格报价 + 授权检查 + 交易数据。无需单独调用——只需遍历 tx_steps 并签名。
• 所有代币，14 条链：所有支持的链上的任意 ERC-20 和原生 gas 代币（ETH、BNB、AVAX、POL 等）。无白名单限制。

何时使用此 Skill

当用户想要执行以下操作时，请使用 WOOFi Swap：

• 在任意 EVM 链上兑换、交易、交换或转换任意代币
• 获取价格报价或两种代币之间的汇率
• 查找 DEX 聚合器中的最优可用价格
• 跨链桥接代币——通过 Stargate 进行跨链兑换
• 买入或卖出特定加密货币
• 构建兑换交易，用于钱包签名和链上执行

---

API 端点

Base URL：https://sapi.woofi.com | 认证：无 | 速率限制：5 req/s | 格式：JSON

灵活输入（所有 V2 端点）

• 链：链 ID（42161）或名称（"arbitrum"）——不区分大小写，会去除空格/短横线
• 代币：地址（"0xaf88..."）或符号（"USDC"）——通过本地索引、静态清单、别名表和外部 API 回退进行解析

---

1. 获取报价 — POST /v2/quote

返回最优可用价格。只读——不生成交易。

参数	类型	必填	默认值	描述
chain	int | str	是	—	链 ID 或名称
sell_token	str	是	—	代币地址或符号
buy_token	str	是	—	代币地址或符号
sell_amount	str	是	—	人类可读数量（例如 "1000"）
slippage_pct	float	否	0.5	最大滑点 %

响应：chain、sell_token、buy_token、sell_amount、buy_amount、price、guaranteed_price

curl -X POST "https://sapi.woofi.com/v2/quote" \
  -H "Content-Type: application/json" \
  -d '{"chain": "arbitrum", "sell_token": "USDC", "buy_token": "WETH", "sell_amount": "1000"}'

---

2. 执行兑换 — POST /v2/swap

单次调用兑换：报价 + 授权检查 + 交易构建，全部在一个响应中完成。后端从所有来源获取最优价格，检查钱包授权状态，并将所有内容打包进 tx_steps。

参数	类型	必填	默认值	描述
chain	int | str	是	—	链 ID 或名称
sell_token	str	是	—	代币地址或符号
buy_token	str	是	—	代币地址或符号
sell_amount	str	是	—	人类可读数量
to	str	是	—	接收钱包地址
rebate_to	str	是	—	返佣地址（通常与 to 相同）
slippage_pct	float	否	0.5	最大滑点 %
signer_address	str	否	null	钱包地址（用于授权检查）

响应（扩展报价）：needs_approve、tx_steps——按顺序遍历并签名每笔交易。

curl -X POST "https://sapi.woofi.com/v2/swap" \
  -H "Content-Type: application/json" \
  -d '{"chain": "arbitrum", "sell_token": "USDC", "buy_token": "WETH", "sell_amount": "1000", "to": "0xYourWallet", "rebate_to": "0xYourWallet", "signer_address": "0xYourWallet"}'

---

3. 跨链报价 — POST /v2/cross_chain/quote

通过 Stargate 桥接进行跨链兑换的报价。只读。

参数	类型	必填	默认值	描述
src_chain	int | str	是	—	源链 ID 或名称
dst_chain	int | str	是	—	目标链 ID 或名称
src_token	str	是	—	源代币（基于 src_chain 解析）
dst_token	str	是	—	目标代币（基于 dst_chain 解析）
src_amount	str	是	—	人类可读的数量
slippage_pct	float	否	1.0	滑点容忍度 %

响应：src_chain、dst_chain、src_amount、dst_amount、bridge_amount_in、bridge_amount_out、price_f

curl -X POST "https://sapi.woofi.com/v2/cross_chain/quote" \
  -H "Content-Type: application/json" \
  -d '{"src_chain": "arbitrum", "dst_chain": "base", "src_token": "USDC", "dst_token": "USDC", "src_amount": "100"}'

---

4. 跨链兑换 — POST /v2/cross_chain/swap

构建通过 Stargate 桥接进行跨链兑换的交易。

参数	类型	必填	默认值	描述
src_chain	int | str	是	—	源链 ID 或名称
dst_chain	int | str	是	—	目标链 ID 或名称
src_token	str	是	—	源代币（基于 src_chain 解析）
dst_token	str	是	—	目标代币（基于 dst_chain 解析）
src_amount	str	是	—	人类可读的数量
to	str	是	—	目标链上的接收方
slippage_pct	float	否	1.0	滑点容忍度 %
signer_address	str	否	null	签名者地址（用于授权检查）

响应（继承跨链报价）：native_fee、needs_approve、tx_steps

curl -X POST "https://sapi.woofi.com/v2/cross_chain/swap" \
  -H "Content-Type: application/json" \
  -d '{"src_chain": "arbitrum", "dst_chain": "base", "src_token": "USDC", "dst_token": "USDC", "src_amount": "100", "to": "0xYourWallet", "signer_address": "0xYourWallet"}'

---

支持的链

链	ID	原生代币	接受的名称
Arbitrum	42161	ETH	arbitrum, arb, arbitrumone
Base	8453	ETH	base
BSC	56	BNB	bsc, bnb, binance, bnbchain
Polygon	137	POL	polygon, matic, pol
Optimism	10	ETH	optimism, op
Avalanche	43114	AVAX	avalanche, avax
Ethereum	1	ETH	ethereum, eth, mainnet
Linea	59144	ETH	linea
Mantle	5000	MNT	mantle
Sonic	146	S	sonic
Berachain	80094	BERA	berachain, bera
HyperEVM	999	HYPE	hyperevm, hyper
Monad	143	MON	monad
zkSync	324	ETH	zksync, zksyncera

原生代币：使用符号（"ETH"、"BNB"、"AVAX"、"POL"、"MNT"、"S"、"BERA"、"MON"）或 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE。

---

重要说明

1. 设计上最优价格 — WOOFi 同时查询 WooPP + 1inch + ODOS。价格 >= 所有来源中的最大值。
2. 灵活的输入 — 链名称（"arbitrum"）和代币符号（"USDC"）在任何地方都可接受。无需地址查询。
3. 一次调用，完整兑换 — /v2/swap 返回报价 + 授权检查 + 交易数据。只需遍历 tx_steps 并签名。
4. 通过 Stargate 跨链 — /v2/cross_chain/swap 在链之间桥接代币。tx_steps 在 value 字段中包含 LayerZero 费用。
5. 人类可读的数量 — 传入 "1.5" 而不是 wei。输入无需单位转换。
6. 支持所有代币 — 任何支持链上的任何 ERC-20 或原生 gas 代币。无白名单。
7. 跨链代币解析 — src_token 基于 src_chain 解析，dst_token 基于 dst_chain 解析。相同的符号会映射到各链上正确的地址。
8. 需要钱包签名 — API 返回未签名的交易数据。用户的钱包必须签名并广播。