layerzero-value-transfer

LayerZero 价值转移 API

用于在 170 条区块链之间转移资产的统一 REST API。一个端点整合了 多个跨链/兑换协议 —— 你获取报价、签名返回的交易，然后 轮询完成状态。Gas 仅在源链上支付。

Base URL： https://transfer.layerzero-api.com/v1

认证（Starchild）：密钥由 sc-proxy 注入 —— 你不需要设置 LAYERZERO_API_KEY。 transfer.layerzero-api.com 是代理域名，因此请通过 core.http_client 路由 transfer 调用，平台会添加真实密钥。 x-api-key 请求头的值可以是任意内容（或省略）；代理会覆盖它。

from core.http_client import proxied_post, proxied_get
r = proxied_post(
    "https://transfer.layerzero-api.com/v1/quotes",
    json=body,
    headers={"x-api-key": "proxy", "SC-CALLER-ID": f"chat:{thread_id}"},
    timeout=40,
)

发现端点（/chains、/tokens、/metadata）无需认证，也可直接 用普通 curl 访问。直接对 transfer 端点执行 curl 会绕过代理并 返回 {"error": "Unauthorized"} —— 任何需要密钥的操作请使用 proxied_*。

路由类型

路由	协议
OFT	标准全链代币转移
STARGATE_V2_TAXI	即时 Stargate 转移
STARGATE_V2_BUS	批量（更便宜、更慢）Stargate 转移
CCTP	Circle 原生 USDC
AORI	基于意图的兑换（使用 EIP-712 签名）

API 会选择最优路由；通常你不需要自行选择。

工作流

1. GET  /chains, /tokens        → discover routes (optional)
2. POST /quotes                 → get quote.id, feeUsd, userSteps
3. Execute userSteps            → sign & send each tx (or EIP-712 signature)
4. GET  /status/{quoteId}       → poll every ~4s until terminal

1. 发现

curl -s https://transfer.layerzero-api.com/v1/chains
# → { "chains": [{ "name": "Base", "chainKey": "base", "chainType": "EVM",
#                 "chainId": 8453, "nativeCurrency": { "symbol": "ETH", "decimals": 18,
#                 "address": "0xEeee...EEeE" } }, ...] }
# Note: results are under the "chains" key (not a bare array). chainType is
# uppercase: EVM, SOLANA, APTOS, SUI, TON, TRON, STARKNET, IOTAMOVE.

# Tokens receivable from a given source token:
curl -s "https://transfer.layerzero-api.com/v1/tokens?transferrableFromChainKey=base&transferrableFromTokenAddress=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"
# → { "tokens": [{ chainKey, address, decimals, symbol, name, price.usd }, ...],
#     "pagination": { "nextToken"? } }   (results under the "tokens" key)

• 原生代币地址为 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE。
• 列表端点分页：传入 pagination[nextToken] 并持续获取，直到 响应中没有 nextToken。
• GET /metadata 返回每条链上的合约部署地址。

2. 获取报价

from core.http_client import proxied_post
r = proxied_post(
    "https://transfer.layerzero-api.com/v1/quotes",
    json={
        "srcChainKey": "base",
        "dstChainKey": "optimism",
        "srcTokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
        "dstTokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
        "srcWalletAddress": "0xYOUR_WALLET",
        "dstWalletAddress": "0xYOUR_WALLET",
        "amount": "1000000000000000",
        "options": {
            "amountType": "EXACT_SRC_AMOUNT",
            "feeTolerance": {"type": "PERCENT", "amount": 2},
        },
    },
    headers={"x-api-key": "proxy", "SC-CALLER-ID": f"chat:{thread_id}"},
    timeout=40,
)
quote = r.json()["quotes"][0]   # id, feeUsd, dstAmount, userSteps

响应结构：{"error": null, "quotes": [{ "id", "routeSteps", "fees", "feeUsd", "feePercent", "srcAmount", "dstAmount", "dstAmountMin", "userSteps" }]}。 quotes 是数组（API 可能返回多条路由）；除非你想比较 feeUsd， 否则取 quotes[0]。

• amount 是一个字符串，采用代币的本地精度（ETH 为 wei）。
• 响应：quote.id、quote.feeUsd、quote.userSteps（按顺序执行的交易）。 在执行前向用户展示 feeUsd 和预期输出。

3. 执行 userSteps

EVM： 按顺序遍历 userSteps；每一步都包含可直接发送的交易 calldata。用 Agent 钱包签名、发送，并在下一步之前等待确认。 ERC-20 转移通常会产生两步：approve，然后跨链交易。

Solana： 交易 blockhash 约 60 秒后过期，因此首先要重新生成最新数据：

r = proxied_post(
    "https://transfer.layerzero-api.com/v1/build-user-steps",
    json={"quoteId": "QUOTE_ID"},
    headers={"x-api-key": "proxy", "SC-CALLER-ID": f"chat:{thread_id}"},
)

签名步骤（如 AORI 等意图路由）： 对 userStep.signature.typedData 中的 EIP-712 载荷签名，然后提交：

r = proxied_post(
    "https://transfer.layerzero-api.com/v1/submit-signature",
    json={"quoteId": "QUOTE_ID", "signatures": ["0xSIGNATURE"]},
    headers={"x-api-key": "proxy", "SC-CALLER-ID": f"chat:{thread_id}"},
)

4. 轮询状态

from core.http_client import proxied_get
r = proxied_get(
    "https://transfer.layerzero-api.com/v1/status/QUOTE_ID",
    params={"txHash": "0xSRC_TX_HASH"},
    headers={"x-api-key": "proxy", "SC-CALLER-ID": f"chat:{thread_id}"},
)
# → { "status": "PROCESSING", "explorerUrl": "..." }

每约 4 秒轮询一次。终态：SUCCEEDED、FAILED、UNKNOWN。 非终态：PENDING、PROCESSING。把 explorerUrl 分享给用户。

安全规则

• ⚠️ 绝不要将 LZMulticall（Wrapper）合约授权为代币花费者。 API 生成的 calldata 已使用 TransferDelegate 合约进行授权 —— 按返回结果执行步骤，不要手工构造授权。
• 报价会过期 —— 如果执行延迟，请重新获取报价；不要复用旧的报价。
• 在签名/发送真实价值交易之前，务必与用户确认： 说明源链/目标链、代币、金额和 feeUsd。
• 在报价前，确认目标地址与用户意图一致。
• 遇到 FAILED 或 UNKNOWN 时，报告 explorerUrl，不要盲目重试。