1. Are there ANY bridges that originate at fromChain?

onchainos cross-chain bridges --from-chain < fromChain

2. Are there ANY bridges that reach toChain?

onchainos cross-chain bridges --to-chain

<

toChain

>

Query 1 empty

→

fromChain

is not in any bridge:

"{fromChain} is not currently supported by any cross-chain bridge. Pick a supported source chain (Ethereum / Arbitrum / Base / Optimism / BSC / Polygon / …)."

Query 1 non-empty, query 2 empty

→

toChain

not reachable from anywhere; user picked an unsupported destination:

"{toChain} cannot be reached by any cross-chain bridge. Pick a supported destination."

Both non-empty

→ both chains supported individually, but no bridge connects this

specific

pair:

"Cannot bridge {fromChain} → {toChain} — no bridge connects this pair. Try a two-hop route via a common chain (Ethereum / Arbitrum)."

Skip the quote step entirely whenever the pair-specific query returns empty.

Step 3 — Quote

onchainos cross-chain quote

\

--from

<

address

>

--to

<

address

>

\

--from-chain

<

chain

>

--to-chain

<

chain

>

\

--readable-amount

<

amount

>

\

--wallet

<

walletAddress

>

--check-approve

\

[

--bridge-id

<

id

>

]

[

--sort

<

0

|

1

|

2

>

]

\

[

--allow-bridges

<

ids

>

]

[

--deny-bridges

<

ids

>

]

--wallet --check-approve

makes the server compare on-chain allowance and fill

routerList[].needApprove

accurately.

Fixed table header (translate to user's language per the global language rule):

| # | Bridge | Est. Receive | Min. Receive | Fee | Est. Time | Approve |

|---|--------|-------------|-------------|-----|-----------|---------|

Column sources:

Column

API Source (in

routerList[]

)

Default if empty

Bridge

bridgeName

—

Est. Receive

toTokenAmount

(UI units + symbol)

—

Min. Receive

minimumReceived

(UI units + symbol)

—

Fee

crossChainFee

(UI units + token symbol) + (if non-zero)

otherNativeFee

0

Est. Time

estimateTime

seconds → human (

~43s

,

~6min

)

—

Approve

needApprove

→

Yes

/

No

. Explain inline below the table — never leave the user guessing what "No" means:

true

→ "approve {readableAmount} to the {bridgeName} router (each bridge needs its own approval the first time)";

false

→ "on-chain allowance for {bridgeName} already ≥ {readableAmount}, no re-approval needed".

No

After displaying the quote table:

routerList[]

is a multi-bridge list. Render every entry as a row in the table — do NOT collapse to one row even when only one is returned today.

Recommend route #1 (server's top pick by current

sort

param) with a brief reason: lowest fee / fastest / max output (decode from the row vs. siblings).

Let the user confirm or pick a different row. If they pick non-default, capture the chosen

bridgeId

and pass it to

execute --bridge-id

.

If the user's reply after a multi-row quote is

anything else

(a fresh trading intent, an unrelated question, or a generic confirmation like "yes" / "go" without referencing a route),

do NOT pick a default and proceed

. Re-prompt asking which route to use, listing the row numbers and bridge names from the quote table (translate to the user's language per the global rule).

Only when the quote table has exactly one row may the agent treat a generic "yes" as confirmation of that single route. With multiple rows, ambiguity defaults to re-prompt, never auto-pick.

Step 4 — User Confirmation

Risk checks (apply before asking for confirmation):

Balance / gas already verified in Step 2.

routerList

empty → see

Fallback: No Direct Route

below.

priceImpactPercentage > 10%

→ WARN prominently (may be empty string in pre-prod; treat as 0%).

receiveAddress != wallet

→ see

Fund-action Flag Gates

for the second-confirmation rule.

Quote freshness (10-second rule)

see Global Notes → "Quote freshness (rolling baseline)". In short: if >10 s have passed since the last user-confirmed quote, re-run

quote

and compare

toTokenAmount

against the prior baseline

minimumReceived

; warn + re-confirm when it dropped.

Step 5 — Execute

6a. First call — default mode (let CLI decide)

onchainos cross-chain execute

\

--from

<

address

>

--to

<

address

>

\

--from-chain

<

chain

>

--to-chain

<

chain

>

\

--readable-amount

<

amount

>

\

--wallet

<

walletAddress

>

\

[

--bridge-id

<

id

>

|

--route-index

<

n

>

]

[

--sort

<

0

|

1

|

2

>

]

\

[

--receive-address

<

addr

>

]

[

--mev-protection

]

Pin a route by either

--bridge-id

(the openApiCode from

quote.routerList[].bridgeId

) or

--route-index

(zero-based index into

quote.routerList[]

). The two flags are mutually exclusive — pass only one.

Three possible outcomes:

action=execute

allowance was sufficient, swap broadcast completed. Show result (Step 7).

action=approve-required

bridge router needs approval. CLI returns:

{ "action": "approve-required", "tokenAddress", "tokenSymbol",

"approveAmount", "readableAmount", "bridgeId", "bridgeName",

"needCancelApprove", "estimateTime", "minimumReceived",

"toTokenAmount", "crossChainFee" }

Display these four facts to the user (translate per global rule):

Spender

:

{bridgeName}

router contract.

Amount

:

{readableAmount}

.

Revoke first?

if

needCancelApprove == true

, note "this token requires revoking the existing allowance first (USDT pattern)".

Net effect

~

{minimumReceived}

arriving on the destination chain after

~{estimateTime}s

.

Then ask "confirm to proceed?".

If user agrees → Step 5b. If user wants different amount → run

quote

again with that amount (uncommon; default is the trade amount). If declines → stop.

error: "execution reverted" / "transaction simulation failed"

TEE pre-execute simulation rejected the swap. See "Step 5a — handling

execution reverted

" below.

Step 5a — handling

execution reverted

When you receive an

execution reverted

/

transaction simulation failed

error from

execute

:

If the error response carries a reason field

(e.g.

failReason

,

message

,

reason

, or an underlying RPC

revert reason

): show the original text to the user and give targeted advice based on what the field implies (insufficient allowance → suggest re-approving; slippage triggered → widen slippage or re-quote; insufficient balance → top up gas; etc.).

If the error response has no specific reason

(only

error: "execution reverted"

/

transaction simulation failed

with no extra fields): tell the user "the bridge contract reverted without a specific reason. This is usually router-internal state, liquidity, or transient backend inconsistency. Suggested next steps: (a) wait 1–3 minutes and retry; (b) try a different bridge (

--bridge-id

); (c) try a different amount."

Do NOT run the

gateway simulate

second-pass diagnostic

in the default flow. Only run it if the user explicitly asks for deeper investigation.

6b. User confirms authorization

Apply the

Quote freshness (rolling baseline)

rule from Global Notes before proceeding.

onchainos cross-chain execute

..

. --confirm-approve

CLI internally:

If

needCancelApprove=true

, calls

/approve-tx?approveAmount=0

and broadcasts the revoke tx (no

approveTxHash

returned for revoke — only the final approve matters).

Calls

/approve-tx

with the user's amount, broadcasts.

Returns

action=approved

with

approveTxHash

. Display:

"Authorization TX submitted: {approveTxHash}"

Proceed to Step 6 (approval polling).

6c. After approval confirmed → execute swap

onchainos cross-chain execute

..

. --skip-approve

CLI skips the approve check and goes straight to

/swap

→ broadcast → returns

action=execute

with

fromTxHash

.

Step 6 — Approval Polling (in main conversation)

After

action=approved

, poll the approval transaction status

in the main conversation

with a bash loop. Do NOT use a sub-agent. Do NOT show raw API output to the user.

for

i

in

$(

seq

1

30

)

;

do

out

=

$(

ONCHAINOS_HOME

=

..

. onchainos --base-url

..

. wallet

history

\

--order-id

<

approveOrderId

>

--chain

<

fromChainIndex

>

2

>

/dev/null

)

st

=

$(

echo

"

$out

"

|

python3

-c

"import sys,json

;

d

=

json.load

(

sys.stdin

)

;

print

((

d.get

(

'data'

)

or

[

{

}

]

)

[

0

]

.get

(

'txStatus'

,

''

))

")

th=

$(

echo

"

$out

"

|

python3

-c

"import sys,json

;

d

=

json.load

(

sys.stdin

)

;

print

((

d.get

(

'data'

)

or

[

{

}

]

)

[0].get('txHash',''))"

)

echo

"Check #

$i

status= ${st :- pending} txHash= $th " case " $st " in SUCCESS ) break ; ; FAIL | FAILED ) break ; ; esac sleep 2 done Key points: Read from data[0].txStatus (array), not data.txStatus . Break immediately on SUCCESS / FAIL ; never run all 30 iterations once the answer is known. Put sleep 2 at the end of the loop body so the first check fires immediately. Echo a status line every iteration so the user sees progress — even when the tool-layer buffering delays display, the final snapshot is still meaningful. Report progress to the user (translate to the user's language): Not yet confirmed (empty status or PENDING ): "Check #{n}: authorization not yet confirmed" Confirmed ( SUCCESS ): "Check #{n}: authorization confirmed" Failed ( FAIL / FAILED ): "Check #{n}: authorization failed" Stop when txStatus = SUCCESS or FAIL , or after 30 attempts (60 s timeout). Handle: Success → apply the Quote freshness (rolling baseline) rule from Global Notes against the most recent user-confirmed quote (Step 5b re-quote if any, else Step 5a internal quote, else Step 3). If still fresh / acceptable, auto-proceed to Step 5c ( execute --skip-approve ). Failed → "Approval transaction failed. Check the gas balance on the source chain or retry later." Timeout (30 attempts) → "Approval confirmation timed out. The transaction may still be pending. Use wallet history --order-id {approveOrderId} to check status manually." Step 7 — Report Result Cross-chain transfer broadcast. Route: {selectedRoute} From: {fromAmount} {fromTokenSymbol} on {fromChain} Expected arrival: ~{toAmount} {toTokenSymbol} on {toChain} Minimum guaranteed: {minimumReceived} {toTokenSymbol} Bridge fee: {crossChainFee} {fromTokenSymbol} Estimated time: ~{estimateTime} seconds Source TX: {fromTxHash} Order ID: {swapOrderId} Bridge: {bridgeName} (id={bridgeId}) Source chain: {fromChain} ({fromChainIndex}) To check arrival status, choose either: - Tell me in chat with the tx hash, e.g. "check if tx {fromTxHash} has arrived". I will run the command for you. - Run directly in terminal (either form works; --bridge-id and --from-chain are REQUIRED in both): onchainos cross-chain status --tx-hash {fromTxHash} --bridge-id {bridgeId} --from-chain {fromChainIndex} onchainos cross-chain status --order-id {swapOrderId} --bridge-id {bridgeId} --from-chain {fromChainIndex} The natural-language phrasing MUST always include the actual fromTxHash value verbatim . Do NOT suggest bare phrases like "check status" — by the time the user follows up, the conversation context may have shifted (other tasks, other tx hashes, a new session) and the agent will not know which transaction the user means. Always anchor the suggested phrasing to the specific tx hash returned by this broadcast. Example phrasings to suggest (translate to the user's language at output time, but always keep the tx hash inline): check if tx 0xabc... has arrived did 0xabc... land on {toChain} yet When the user says something vague after broadcast — e.g. "你查吧", "查一下", "check it", "has it arrived", "查 order xxx" with only the order-id — the agent MUST recall and reuse the full triple from the most recent execute response in this conversation: fromTxHash (or swapOrderId ) bridgeId fromChainIndex NEVER call cross-chain status --order-id alone — that omits two required args and clap will reject it. Always join the recalled bridgeId + fromChainIndex from the same execute that produced the order-id. If the conversation has moved on and you no longer have the triple cached, ask the user to confirm bridgeId and fromChain , do not guess. Use business-level language. Do NOT say "Transaction confirmed on-chain" or "Cross-chain complete" — broadcast does not guarantee delivery; bridges process asynchronously. Step 8 — Status Tracking User queries status after estimated arrival time. Either form works (use whichever identifier the user has on hand); the other two args are not optional :

By source-chain tx hash

onchainos cross-chain status --tx-hash < fromTxHash

--bridge-id < bridgeId

--from-chain < fromChainIndex

By order id (resolved internally to tx hash via /order/detail; login required)

onchainos cross-chain status --order-id

<

swapOrderId

>

--bridge-id

<

bridgeId

>

--from-chain

<

fromChainIndex

>

Recall

bridgeId

+

fromChainIndex

from the most recent

execute

response in this conversation. See the IMPORTANT block in Step 7 for the "vague follow-up" rule.

Interpret

status

field:

Status

User Message

SUCCESS

"Cross-chain transfer complete. {toAmount} {toTokenSymbol} arrived on {toChain}. Destination TX: {toTxHash}"

PENDING

"Transfer in progress. Bridge: {bridgeId mapped to name}. Check again shortly. Estimated arrival: ~{originalEstimateTime}."

NOT_FOUND

First few seconds after broadcast: "Bridge has not yet indexed your transaction. Wait 10–30s and re-check." Long persistence (>5 min): "Transaction not visible to the bridge monitor yet. The source chain may not have confirmed it. Verify on the source chain explorer: {explorerUrl}."

Polling cadence (recommended)

exponential backoff — 10s → 20s → 40s → 60s → 60s. Stop polling after SUCCESS or after originalEstimateTime × 5 total elapsed. onchainos wallet balance --chain < toChain

--force If the destination balance has increased by ~ minimumReceived (or the destination explorer shows an incoming transfer from the bridge router), funds have already arrived . The PENDING is a backend-listener gap (most often seen on ACROSS V3), not a missing fill. Tell the user the funds are already on the destination chain (cite balance / explorer) and stop polling — status will reconcile eventually but is not gating fund availability. See references/troubleshooting.md → " status stuck at PENDING" for the two-case decision tree. Escalation to OKX support — guide the user when: NOT_FOUND persists for > 4 hours after broadcast. PENDING persists for > original estimateTime × 10 AND destination chain shows no fill. Any abnormal state with no progress for > 4 hours. Always provide: fromTxHash + bridgeName (looked up via bridgeId ). The status API does not return refund / failure sub-states. For long-stuck transactions, point users to the destination chain explorer (or wallet balance ) first, then the bridge protocol's own scan page (Stargate / ACROSS / Relay scan) for bridge-side progress. Fallback: No Direct Route When cross-chain quote returns 82000 (no liquidity) / 82104 (token unsupported) / empty routerList : Try transit tokens automatically — call quote again with USDC, USDT, and native (ETH/BNB/etc.) as the "via" asset between the two chains:

1. Discover transit options

for

transit

in

usdc usdt eth

;

do

onchainos cross-chain quote

\

--from

$transit

--to

$transit

\

--from-chain

<

fromChain

>

--to-chain

<

toChain

>

\

--readable-amount

<

amount estimate

>

done

If at least one transit succeeds

— display the list and let the user choose:

{tokenSymbol} cannot be bridged directly from {fromChain} to {toChain}. These tokens are bridgeable:

| # | Transit Token | Est. Receive | Fee | Est. Time |

|---|--------------|-------------|-----|-----------|

| 1 | USDC | 99.98 | 0.04| ~45s |

| 2 | USDT | 99.92 | 0.08| ~50s |

Pick a transit token. Steps:

1. Swap {tokenSymbol} → {transit} on {fromChain} (use okx-dex-swap)

2. Bridge {transit} from {fromChain} to {toChain} (use okx-dex-bridge)

3. Swap {transit} → {targetToken} on {toChain} (use okx-dex-swap)

If all transits fail

— when surfacing the failure to the user,

always prefer the backend

msg

(the text after

code=NNNNN:

) over a code-based interpretation. The agent's job here is to translate the server's reason into the user's language, not to invent meanings for codes.

Three sub-cases:

Responses carry a non-empty

msg

(e.g.

API error (code=82000): no available route for this token pair on this chain

):

Translate the

msg

into the user's language and surface it directly. Add the actionable next step (

{tokenSymbol} can't be bridged from {fromChain} to {toChain}: {translated msg}.

). Do NOT mention the raw code.

All responses are

code=82000

with no usable

msg

(CLI prints

API error (code=82000): unknown error

— server returned an empty / missing

msg

):

"Bridge service for {fromChain} ↔ {toChain} appears unavailable on this environment. The chain pair is in the routing config but

quote

returns no reason across the direct route and every transit token. This is typically a server-side / environment issue (the chain's bridge adapter is not wired up here), not a problem with your token or amount. Please retry later, or escalate to OKX support if it persists. Source-chain explorer: {explorerUrl}."

Mixed responses across direct + transits

— truly no path:

"{tokenSymbol} cannot be bridged from {fromChain} to {toChain}. No common transit token (USDC/USDT/native) is bridgeable either."

Sort transit results by total fee ascending. Step 2 only shown when the destination target differs from the transit token.

Risk Controls

Risk Item

Action

Notes

No quote available

FALLBACK

Run transit token discovery (above)

Heterogeneous chain pair (EVM↔non-EVM)

NOT SUPPORTED

Tell user "currently no bridge supports this pair"

Price impact > 10% (

priceImpactPercentage

)

WARN

Pre-prod may return empty; treat as 0%

receiveAddress != wallet

WARN

"Wrong destination address = permanent fund loss." Require explicit re-confirmation

Black/flagged address (82200)

BLOCK

Address flagged by security

Backend risk warning (81362) on broadcast

WARN + require explicit confirm + re-run with

--force

Only after user explicitly confirms

Insufficient source token balance

BLOCK

Show current balance, required amount

Insufficient gas balance

BLOCK

Remind user gas is insufficient

Legend

BLOCK = halt, do not proceed. WARN = display warning, ask confirmation. FALLBACK = run transit discovery. NOT SUPPORTED = explain limitation, propose two-hop workaround.

Fund-action Flag Gates

Every flag that broadcasts a transaction or expands the agent's spending authority requires an explicit user-confirmation gate. Do NOT pass any of these flags without a clear user yes/no.

Flag

Effect

Required user gate

--confirm-approve

Broadcasts ERC-20 approve tx (granting allowance to bridge router)

Show approveAmount + spender (bridge name) + needCancelApprove → only proceed when the user explicitly confirms (yes / approve)

--skip-approve

Skips on-chain allowance check, broadcasts swap directly

Only after a successful prior

--confirm-approve

in the same flow, with poll-confirmed approve txStatus=success

--force

Bypasses backend risk warning 81362 (potential honeypot / poisoned contract)

After receiving 81362,

must explicitly tell user

the risk is "potential fund loss"; only re-run with

--force

if the user explicitly confirms (yes / continue)

--bridge-id

/

--route-index

Pins a specific bridge (overrides server-default optimal route)

Either (a) the user picked from the displayed quote table, or (b) the user named a bridge by name; do NOT pin without an instruction

--allow-bridges

/

--deny-bridges

Restricts the bridge selection set

Only when the user said "use only X" or "don't use X"; never pre-emptively

--receive-address

≠ wallet

Sends funds to a non-sender address

Display "Wrong destination = permanent fund loss" + require

second confirmation

of the address

--mev-protection

Adds MEV-protection broadcast (cost may be higher)

Auto-set by chain threshold rule (see MEV Protection); user override allowed

Silent / Automated mode

Skips per-step user yes/no

Requires

prior explicit opt-in

by the user. BLOCK-level risks still halt and notify. PAUSE-level risks still wait for yes/no even in silent mode.

Rule

when in doubt, ask. A delayed confirm is far better than a wrong broadcast.

MEV Protection

Calculate

txValueUsd = fromTokenAmount × fromTokenPrice

and pass

--mev-protection

only when

txValueUsd >= threshold

for the source chain:

Chain

Threshold

How to enable

Ethereum

$2,000

--mev-protection

BNB Chain

$200

--mev-protection

Base

$200

--mev-protection

Solana

—

Not yet wired for cross-chain (no Solana cross-chain currently)

Others

No MEV protection available

—

If

fromTokenPrice

is unavailable → enable by default (safe).

Re-evaluate every time the amount changes

— do NOT carry over

--mev-protection

from a previous command when the user modifies the amount.

Amount Display Rules

Display amounts in UI units:

1.5 ETH

,

3,200 USDC

.

CLI

--readable-amount

accepts human-readable amounts; CLI converts to raw units automatically.

Bridge fees in source token UI units (e.g.

0.044 USDC

).

minimumReceived

in destination token UI units.

estimateTime

in human-friendly format:

~43 seconds

,

~5 minutes

.

Always show both source and destination chain + token in displays.

Global Notes

exactIn only

cross-chain always uses exactIn mode. User specifies source amount; destination amount is determined by the bridge protocol. Do NOT attempt exactOut.

EVM addresses must be all lowercase

— both in CLI parameters (

--from

/

--to

/

--receive-address

) AND when displaying to the user. Convert mixed-case immediately. Solana addresses are case-sensitive — keep as-is.

Quote freshness (rolling baseline)

every comparison uses the

last user-confirmed quote

as the baseline (Step 3 → Step 4 re-quote → Step 5a internal quote → Step 5b re-quote → Step 6 re-quote, whichever is most recent). If >10 s pass since that baseline, re-fetch quote and compare new

toTokenAmount

with the baseline's

minimumReceived

. Once user confirms a fresh quote, it becomes the new baseline.

Non-atomic

source chain broadcast does not guarantee destination arrival. Funds may be in transit for seconds to minutes. Do not tell the user "transaction complete" until status returns SUCCESS.

API fallback

if the CLI is unavailable, the OKX DEX cross-chain OpenAPI is documented at

https://web3.okx.com/onchainos/dev-docs/trade/cross-chain-api-reference

. Prefer CLI when available.

Silent / Automated Mode

Enabled only when the user has

explicitly authorized

automated execution. Three mandatory rules:

Explicit authorization

user must clearly opt in. Never assume silent mode.

Risk gate pause

BLOCK-level risks must halt and notify even in silent mode. Cross-chain

receiveAddress != wallet

confirmation cannot be skipped.

Execution log

log every silent transaction (timestamp, pair, amount, route, fromTxHash, status). Present on request or at session end. Additional Resources references/cli-reference.md — full params, return fields, and examples for all 7 commands. Edge Cases Load on error: references/troubleshooting.md