layerzero-value-transfer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

LayerZero Value Transfer API

Unified REST API for moving assets across 170 blockchains. One endpoint consolidates multiple bridge/swap protocols — you get a quote, sign the returned transactions, and poll for completion. Gas is paid on the source chain only.

Base URL:

https://transfer.layerzero-api.com/v1

Auth (Starchild): the key is injected by sc-proxy — you do NOT set
LAYERZERO_API_KEY
.

transfer.layerzero-api.com

is a proxied domain, so route transfer calls through

core.http_client

and the platform adds the real key. The

x-api-key

header value can be anything (or omitted); the proxy overrides it.

python

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,
)

Discovery endpoints (

/chains

/tokens

/metadata

) need no auth and work with plain

curl

too. A direct

curl

to a transfer endpoint bypasses the proxy and returns

{"error": "Unauthorized"}

— use

proxied_*

for anything that needs the key.

用于在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

发起转移请求，平台会添加真实密钥。

x-api-key

请求头的值可以是任意内容（或省略）；代理会覆盖该值。

python

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

即可调用。直接用

curl

请求转移类端点会绕过代理并返回

{"error": "Unauthorized"}

——所有需要密钥的请求请使用

proxied_*

方法。

Route types

路由类型

Route	Protocol
`OFT`	Standard omnichain token transfer
`STARGATE_V2_TAXI`	Instant Stargate transfer
`STARGATE_V2_BUS`	Batched (cheaper, slower) Stargate transfer
`CCTP`	Circle native USDC
`AORI`	Intent-based swap (uses EIP-712 signatures)

The API picks the optimal route; you don't normally need to choose.

路由类型	协议说明
`OFT`	标准全链代币转移
`STARGATE_V2_TAXI`	Stargate即时转移
`STARGATE_V2_BUS`	Stargate批量转移（成本更低，速度较慢）
`CCTP`	Circle原生USDC转移
`AORI`	基于意图的兑换（使用EIP-712签名）

API会自动选择最优路由；通常无需手动选择。

Workflow

工作流

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. GET  /chains, /tokens        → 发现可用路由（可选）
2. POST /quotes                 → 获取quote.id、feeUsd、userSteps
3. Execute userSteps            → 签名并发送每笔交易（或EIP-712签名）
4. GET  /status/{quoteId}       → 每约4秒轮询一次直到进入终端状态

1. Discovery

1. 发现资源

bash

curl -s https://transfer.layerzero-api.com/v1/chains

bash

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

注意：结果嵌套在"chains"键下（不是裸数组）。chainType为大写：EVM、SOLANA、APTOS、SUI、TON、TRON、STARKNET、IOTAMOVE。

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)

"pagination": { "nextToken"? } } （结果嵌套在"tokens"键下）


- Native token address is `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`.
- List endpoints paginate: pass `pagination[nextToken]` and keep fetching until
  the response has no `nextToken`.
- `GET /metadata` returns contract deployment addresses per chain.


- 原生代币地址为`0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`。
- 列表类端点支持分页：传递`pagination[nextToken]`参数，持续请求直到响应中没有`nextToken`。
- `GET /metadata`返回各链上的合约部署地址。

2. Get a quote

2. 获取报价

python

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

Response shape:

{"error": null, "quotes": [{ "id", "routeSteps", "fees", "feeUsd", "feePercent", "srcAmount", "dstAmount", "dstAmountMin", "userSteps" }]}

quotes

is an array (the API may return several routes); take

quotes[0]

unless you want to compare

feeUsd

```
amount
```
is a string in the token's local decimals (wei for ETH).
Response:
```
quote.id
```
,
```
quote.feeUsd
```
,
```
quote.userSteps
```
(ordered transactions to execute). Show the user
```
feeUsd
```
and expected output before executing.

python

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. Execute userSteps

3. 执行userSteps

EVM: loop through

userSteps

in order; each contains ready-to-send transaction calldata. Sign with the agent wallet, send, and wait for confirmation before the next step. ERC-20 transfers typically yield two steps:

approve

then the bridge tx.

Solana: transaction blockhashes expire in ~60s, so first regenerate fresh data:

python

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}"},
)

Signature steps (intent routes like AORI): sign the EIP-712 payload in

userStep.signature.typedData

, then submit:

python

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}"},
)

EVM链： 按顺序遍历

userSteps

；每个步骤包含可直接发送的交易调用数据。使用代理钱包签名并发送，等待确认后再执行下一步。ERC-20转移通常包含两个步骤：

approve

（授权）然后是跨链桥交易。

Solana链： 交易区块哈希约60秒后过期，因此需先生成新数据：

python

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负载进行签名，然后提交：

python

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. Poll status

4. 轮询状态

python

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}"},
)

python

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": "..." }


Poll every ~4 seconds. Terminal states: `SUCCEEDED`, `FAILED`, `UNKNOWN`.
Non-terminal: `PENDING`, `PROCESSING`. Share `explorerUrl` with the user.


每约4秒轮询一次。终端状态包括：`SUCCEEDED`（成功）、`FAILED`（失败）、`UNKNOWN`（未知）。
非终端状态包括：`PENDING`（待处理）、`PROCESSING`（处理中）。需将`explorerUrl`分享给用户。

Safety rules

安全规则

⚠️ Never approve the LZMulticall (Wrapper) contract as a token spender. The API-generated calldata already uses the TransferDelegate contract for approvals — execute steps as returned, don't hand-craft approvals.
Quotes expire — get a fresh quote if execution is delayed; don't reuse old ones.
Always confirm with the user before signing/sending real-value transactions: state source/destination chains, token, amount, and
```
feeUsd
```
.
Verify the destination address matches the user's intent before quoting.
On
```
FAILED
```
or
```
UNKNOWN
```
, report the
```
explorerUrl
```
and do not retry blindly.

⚠️ 切勿将LZMulticall（Wrapper）合约授权为代币支出方。 API生成的调用数据已使用TransferDelegate合约进行授权——请按返回的步骤执行，不要手动创建授权操作。
报价会过期——如果执行延迟，请获取新报价；不要重复使用旧报价。
在签署/发送涉及真实价值的交易前，务必与用户确认：告知源链/目标链、代币、金额以及
```
feeUsd
```
。
报价前请验证目标地址是否符合用户意图。
若状态为
```
FAILED
```
或
```
UNKNOWN
```
，请告知用户
```
explorerUrl
```
，不要盲目重试。