Back to Details

openfin-relay

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Relay Bridging

Relay跨链桥接

Playbook for bridging, swapping, and bridge+calling via Relay through OpenFinance.
通过OpenFinance的Relay进行桥接、兑换和桥接并调用的操作手册。

Three operations, one API

三类操作，一个API

OperationWhat it is
SwapSame-chain token swap (origin = destination chain)
BridgeMove tokens across chains (USDC on Polygon → USDC on Base)
Bridge+callBridge + execute a destination-chain tx after the bridge lands — pass the tx(s) in 
txs
Relay picks the route automatically; you just provide the inputs.
操作说明
Swap（兑换）同链代币兑换（源链 = 目标链）
Bridge（桥接）跨链转移代币（Polygon上的USDC → Base上的USDC）
Bridge+call（桥接并调用）完成桥接后在目标链执行交易——在
txs
中传入交易内容
Relay会自动选择路由；你只需提供输入参数即可。

Endpoints

接口

All three require 
x-api-key: open_…
. Relay aggregates liquidity across 40+ chains — you pass the chain IDs directly; the backend picks the route.
所有三个接口都需要携带
x-api-key: open_…
请求头。Relay聚合了40+条链的流动性——你只需直接传入chainId，后端会自动选择路由。

POST /agent/relay/quote
— quote only

POST /agent/relay/quote
— 仅获取报价

Fetches a Relay quote for a swap, bridge, or bridge+call. Does NOT submit any transactions. Use for preview UIs, fee estimation, or to show the user the route before they confirm.
Request body:
json
{
  "originChainId": 137,
  "destinationChainId": 8453,
  "originCurrency": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
  "destinationCurrency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": "10000000",
  "tradeType": "EXACT_INPUT",
  "recipient": "...",               // optional; defaults to user's dest-chain addr
  "slippageTolerance": "50",        // basis points, optional
  "topupGas": true,                 // optional; forced false for Solana routes
  "topupGasAmount": "100000",       // USD micro-units, optional
  "usePermit": false,               // EIP-3009 permit for supported tokens
  "txs": [{"to", "data", "value"}], // optional; for bridge+call
  "appFees": [{"recipient", "fee"}] // optional
}
user
is server-injected from the caller's wallet based on 
originChainId
— do NOT pass it. The backend selects EVM or Solana address automatically.
Returns the full response: 
{steps, fees, feeSponsorship}
. 
steps
is an array of signable/submittable actions (transactions or signatures) with embedded 
check
endpoints for status polling.
获取Relay针对兑换、桥接或桥接并调用的报价。不会提交任何交易。用于预览UI、手续费估算，或在用户确认前展示路由信息。
请求体：
json
{
  "originChainId": 137,
  "destinationChainId": 8453,
  "originCurrency": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
  "destinationCurrency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": "10000000",
  "tradeType": "EXACT_INPUT",
  "recipient": "...",               // 可选；默认值为用户的目标链地址
  "slippageTolerance": "50",        // 基点，可选
  "topupGas": true,                 // 可选；Solana路由强制设为false
  "topupGasAmount": "100000",       // USD微单位，可选
  "usePermit": false,               // 针对支持代币的EIP-3009授权
  "txs": [{"to", "data", "value"}], // 可选；用于桥接并调用
  "appFees": [{"recipient", "fee"}] // 可选
}
user
会由服务器根据调用方的钱包和
originChainId
自动注入——请勿自行传入。后端会自动选择EVM或Solana地址。
返回完整响应：
{steps, fees, feeSponsorship}
。
steps
是可签名/可提交的操作数组（交易或签名），包含用于状态轮询的嵌入式
check
接口。

POST /agent/relay/execute
— quote + sign + submit + poll

POST /agent/relay/execute
— 报价+签名+提交+轮询

End-to-end flow. Same body as 
/quote
. The backend:
  1. Fetches the quote
  2. Walks every 
    step
    :
    • EVM transaction step → sends via viem 
      walletClient.sendTransaction
      on the correct chain, waits for 1 confirmation
    • Solana transaction step → compiles 
      instructions
      + ALTs into a VersionedTransaction, has Privy sign it (
      signTransaction
      ), broadcasts via our RPC with 
      skipPreflight: true
      , confirms with the original blockhash/lastValidBlockHeight
    • EIP-712 signature step → signs with the user's EVM account and POSTs the signature to the step's 
      check.endpoint
  3. Polls 
    GET /intents/status/v3
    with exponential backoff (1s → 10s, 5-min cap) until terminal status
Returns 
{requestId, quote, txHashes, finalStatus}
.
Use when the user confirms the quote or directly asks to bridge / swap / execute. Solana-origin requires the user's Solana wallet to be delegated (see 
openfin-setup
step 2).
端到端流程。请求体与
/quote
相同。后端会执行以下操作：
  1. 获取报价
  2. 处理每一个
    step
    ：
    • EVM交易步骤 → 通过viem 
      walletClient.sendTransaction
      在对应链发送交易，等待1次确认
    • Solana交易步骤 → 将
      instructions
      + ALTs编译为VersionedTransaction，由Privy签名（
      signTransaction
      ），通过我们的RPC广播并设置
      skipPreflight: true
      ，使用原始blockhash/lastValidBlockHeight确认
    • EIP-712签名步骤 → 使用用户的EVM账户签名，并将签名POST到步骤的
      check.endpoint
  3. 使用指数退避策略（1秒→10秒，上限5分钟）轮询
    GET /intents/status/v3
    ，直到达到终端状态
返回
{requestId, quote, txHashes, finalStatus}
。
当用户确认报价或直接要求桥接/兑换/执行时使用此接口。Solana发起的操作要求用户的Solana钱包已完成授权（详见
openfin-setup
步骤2）。

GET /agent/relay/status?requestId=<id>
— manual status lookup

GET /agent/relay/status?requestId=<id>
— 手动查询状态

Get the current status of a Relay intent by its 
requestId
. Use for manual polling from the frontend when 
/execute
wasn't awaited, or for audit lookups.
Status values:
  • waiting
    — awaiting deposit confirmation
  • depositing
    — origin deposit confirmed, pending fill
  • pending
    — deposit confirmed, awaiting destination submission
  • submitted
    — destination transaction submitted
  • delayed
    — destination fill still processing
  • success
     — successful fill on destination (terminal)
  • refunded
     — successfully refunded (terminal)
  • failure
     — unsuccessful fill (terminal)
Response also includes 
details
(free-form text), 
inTxHashes
, 
txHashes
, 
updatedAt
(ms), 
originChainId
, 
destinationChainId
.
通过
requestId
获取Relay意向的当前状态。用于前端未等待
/execute
返回时的手动轮询，或审计查询。
状态值：
  • waiting
    — 等待存款确认
  • depositing
    — 源链存款已确认，等待填充
  • pending
    — 存款已确认，等待目标链提交
  • submitted
    — 目标链交易已提交
  • delayed
    — 目标链填充仍在处理中
  • success
     — 目标链填充成功（终端状态）
  • refunded
     — 退款成功（终端状态）
  • failure
     — 填充失败（终端状态）
响应还包含
details
（自由格式文本）、
inTxHashes
、
txHashes
、
updatedAt
（毫秒）、
originChainId
、
destinationChainId
。

Required inputs

必填输入参数

FieldTypeNotes
originChainId
numberSource chain
destinationChainId
numberDestination chain
originCurrency
stringToken contract on origin (or 
0x0…0
for EVM native)
destinationCurrency
stringToken contract on destination
amount
stringSmallest unit as a STRING (wei for 18-dec, 
10000000
= 10 USDC)
tradeType
string
EXACT_INPUT
| 
EXACT_OUTPUT
| 
EXPECTED_OUTPUT
user
is server-injected based on 
originChainId
— pass the right wallet for the origin. Solana origin → Solana address; EVM origin → EVM address. Do not pass it yourself.
recipient
defaults to the user's address on the destination chain. Override explicitly if bridging to a different address.
字段类型说明
originChainId
数字源链ID
destinationChainId
数字目标链ID
originCurrency
字符串源链上的代币合约地址（EVM原生代币填
0x0…0
）
destinationCurrency
字符串目标链上的代币合约地址
amount
字符串最小单位的字符串形式（18位小数代币用wei，
10000000
= 10 USDC）
tradeType
字符串
EXACT_INPUT
| 
EXACT_OUTPUT
| 
EXPECTED_OUTPUT
user
由服务器自动注入，基于
originChainId
——传入与源链匹配的钱包即可。Solana源链→Solana地址；EVM源链→EVM地址。请勿自行传入。
recipient
默认值为用户在目标链上的地址。如果要桥接到其他地址，请显式覆盖。

Chain ID cheatsheet

Chain ID速查表

ChainID
Ethereum
1
Polygon
137
Base
8453
Optimism
10
Arbitrum
42161
BSC
56
Linea
59144
Blast
81457
Scroll
534352
zkSync Era
324
Hyperliquid
1337
Solana
792703809
Bitcoin
8253038
Tron
728126428
Live list: 
GET https://api.relay.link/chains
. Treat that endpoint as source of truth for supported origin chains.
链名称ID
以太坊
1
Polygon
137
Base
8453
Optimism
10
Arbitrum
42161
BSC
56
Linea
59144
Blast
81457
Scroll
534352
zkSync Era
324
Hyperliquid
1337
Solana
792703809
Bitcoin
8253038
Tron
728126428
实时列表：
GET https://api.relay.link/chains
。请将该接口作为支持的源链的权威数据源。

Native-token sentinel

原生代币标记

Use 
0x0000000000000000000000000000000000000000
for the EVM native token on any EVM chain (ETH / MATIC / BNB / etc.).
For Solana, use 
So11111111111111111111111111111111111111112
for wrapped SOL, or the SPL mint address for tokens (e.g. 
EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
for USDC).
任何EVM链上的原生代币（ETH/MATIC/BNB等）都使用
0x0000000000000000000000000000000000000000
表示。
Solana链上，包装SOL使用
So11111111111111111111111111111111111111112
，代币使用SPL铸币地址（例如USDC的地址为
EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
）。

Trade types

交易类型

TypeMeaningExample
EXACT_INPUT
Send exactly 
amount
, receive variable		"Bridge 10 USDC"
EXACT_OUTPUT
Send variable, receive exactly 
amount
"Get me exactly 1 ETH on Base"
EXPECTED_OUTPUT
Alternate routingRarely needed
Most prompts are 
EXACT_INPUT
. If user says "I want to receive X", use 
EXACT_OUTPUT
.
类型含义示例
EXACT_INPUT
发送固定
amount
，接收数量可变		"桥接10 USDC"
EXACT_OUTPUT
发送数量可变，接收固定
amount
"给我在Base上转1 ETH"
EXPECTED_OUTPUT
备选路由极少使用
大多数场景使用
EXACT_INPUT
。如果用户说“我想收到X”，则使用
EXACT_OUTPUT
。

Gas topup defaults

Gas充值默认设置

Backend behavior:
  • EVM ↔ EVM: 
    topupGas: true
    default, 
    topupGasAmount: "100000"
    ($0.10). Relay only applies it if the recipient needs gas.
  • Any route with Solana (chainId 
    792703809
    )    : 
    topupGas
    forced 
    false
    .
  • Ethereum L1 destination: bump 
    topupGasAmount
    to 
    "500000"
    ($0.50).
Override per-call via body fields 
topupGas
and 
topupGasAmount
.
后端行为：
  • EVM ↔ EVM：默认
    topupGas: true
    ，
    topupGasAmount: "100000"
    （0.10美元）。仅当接收方需要Gas时，Relay才会执行充值。
  • 涉及Solana的路由（chainId 
    792703809
    ）    ：
    topupGas
    强制设为
    false
    。
  • 目标链为以太坊L1：将
    topupGasAmount
    提高到
    "500000"
    （0.50美元）。
可通过请求体字段
topupGas
和
topupGasAmount
覆盖默认设置。

Solana-origin example

Solana源链示例

Bridge the user's USDC from Solana back to USDC.e on Polygon:
json
{
  "originChainId": 792703809,
  "destinationChainId": 137,
  "originCurrency": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "destinationCurrency": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
  "amount": "1000000",
  "tradeType": "EXACT_INPUT"
}
user
auto-fills as the user's Solana address; 
recipient
auto-fills as their EVM address. Requires Solana wallet delegation (see 
openfin-setup
). Without it, execute fails with 412.
将用户的USDC从Solana桥接到Polygon上的USDC.e：
json
{
  "originChainId": 792703809,
  "destinationChainId": 137,
  "originCurrency": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "destinationCurrency": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
  "amount": "1000000",
  "tradeType": "EXACT_INPUT"
}
user
会自动填充为用户的Solana地址；
recipient
自动填充为用户的EVM地址。需要Solana钱包授权（详见
openfin-setup
）。未授权时，执行会返回412错误。

Bridge+call example

桥接并调用示例

Bridge USDC.e Polygon → USDC Base, then call a contract on Base:
json
{
  "originChainId": 137,
  "destinationChainId": 8453,
  "originCurrency": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
  "destinationCurrency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": "10000000",
  "tradeType": "EXACT_INPUT",
  "txs": [
    { "to": "0x…target…", "data": "0x…calldata…", "value": "0" }
  ]
}
将Polygon上的USDC.e桥接到Base上的USDC，然后在Base上调用合约：
json
{
  "originChainId": 137,
  "destinationChainId": 8453,
  "originCurrency": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
  "destinationCurrency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": "10000000",
  "tradeType": "EXACT_INPUT",
  "txs": [
    { "to": "0x…target…", "data": "0x…calldata…", "value": "0" }
  ]
}

Status values

状态值说明

  • Terminal success: 
    success
    , 
    refunded
  • Terminal failure: 
    failure
  • In-flight: 
    waiting
    , 
    depositing
    , 
    pending
    , 
    submitted
    , 
    delayed
If 
/execute
returns non-terminal 
finalStatus
, keep polling 
/status
with the 
requestId
.
  • 终端成功状态：
    success
    、
    refunded
  • 终端失败状态：
    failure
  • 进行中状态：
    waiting
    、
    depositing
    、
    pending
    、
    submitted
    、
    delayed
如果
/execute
返回非终端状态
finalStatus
，请使用
requestId
持续轮询
/status
。

Don't

注意事项

  • Don't use human-readable amounts. 
    "1000000"
    = 1 USDC, not 
    "1"
    .
  • Don't pass 
    user
    or 
    userId
    — server injects.
  • Don't retry a 
    failure
    without checking 
    details
    — refund may be automatic (
    status: refunded
    will follow), or the route may be unsupported.
  • Don't assume Solana delegation carries over from EVM. Each chain type delegates separately in Privy.
  • 请勿使用人类可读的金额。
    "1000000"
    = 1 USDC，而非
    "1"
    。
  • 请勿传入
    user
    或
    userId
    ——由服务器自动注入。
  • 失败状态
    failure
    请勿直接重试，需先查看
    details
    ——退款可能自动完成（后续状态会变为
    refunded
    ），或该路由不被支持。
  • 请勿假设Solana授权与EVM授权互通。Privy中不同链类型的授权是独立的。

MCP note

MCP说明

Tool names match: 
relay_get_quote
, 
relay_execute
, 
relay_get_status
.
工具名称对应：
relay_get_quote
、
relay_execute
、
relay_get_status
。