layerzero-value-transfer

LayerZero Value Transfer API

170 のブロックチェーン間で資産を移動するための統合 REST API です。1 つのエンドポイントが 複数のブリッジ/スワッププロトコルを集約します — 見積もりを取得し、返されたトランザクションに署名し、 完了までポーリングします。ガスはソースチェーンでのみ支払われます。

ベース URL: https://transfer.layerzero-api.com/v1

認証 (Starchild): キーは sc-proxy によって注入されます — LAYERZERO_API_KEY を設定する必要は ありません。 transfer.layerzero-api.com はプロキシされたドメインであるため、転送呼び出しは core.http_client 経由でルーティングすると、プラットフォームが実際のキーを追加します。 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 でも 動作します。転送エンドポイントに直接 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 はトークンのローカル decimals での文字列です (ETH の場合は wei)。
• レスポンス: quote.id、quote.feeUsd、quote.userSteps (実行する順序付けられた トランザクション)。実行前にユーザーに feeUsd と予想される出力を提示してください。

3. userSteps の実行

EVM: userSteps を順番にループします。各ステップには送信可能なトランザクション calldata が含まれます。エージェントウォレットで署名し、送信し、次のステップの前に 確認を待ちます。ERC-20 転送は通常 2 つのステップを生成します: approve とブリッジ トランザクションです。

Solana: トランザクションのブロックハッシュは約 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 を報告し、盲目的に再試行しないでください。