Okx Onchain Gateway

OKX Onchain Gateway CLI

6 commands for gas estimation, transaction simulation, broadcasting, and order tracking.

Pre-flight Checks

Every time before running any onchainos command, always follow these steps in order. Do not echo routine command output to the user; only provide a brief status update when installing, updating, or handling a failure.

1. Confirm installed: Run which onchainos. If not found, install it:

   curl -sSL https://raw.githubusercontent.com/okx/onchainos-skills/main/install.sh | sh
   

   If the install script fails, ask the user to install manually following the instructions at: https://github.com/okx/onchainos-skills

2. Check for updates: Read ~/.onchainos/last_check and compare it with the current timestamp:

   cached_ts=$(cat ~/.onchainos/last_check 2>/dev/null || true)
   now=$(date +%s)
   

   • If cached_ts is non-empty and (now - cached_ts) < 43200 (12 hours), skip the update and proceed.
   • Otherwise (file missing or older than 12 hours), run the installer to check for updates:

     curl -sSL https://raw.githubusercontent.com/okx/onchainos-skills/main/install.sh | sh
     

     If a newer version is installed, tell the user and suggest updating their onchainos skills from https://github.com/okx/onchainos-skills to get the latest features.

3. If any onchainos command fails with an unexpected error during this session, try reinstalling before giving up:

   curl -sSL https://raw.githubusercontent.com/okx/onchainos-skills/main/install.sh | sh
   

4. Create a .env file in the project root to override the default API credentials (optional — skip this for quick start):

   OKX_API_KEY=          # or OKX_ACCESS_KEY
   OKX_SECRET_KEY=
   OKX_PASSPHRASE=
   

Skill Routing

• For swap quote and execution → use okx-dex-swap
• For market prices → use okx-dex-market
• For token search → use okx-dex-token
• For wallet balances / portfolio → use okx-wallet-portfolio
• For transaction broadcasting → use this skill (okx-onchain-gateway)

Quickstart

# Get current gas price on XLayer
onchainos gateway gas --chain xlayer

# Estimate gas limit for a transaction
onchainos gateway gas-limit --from 0xYourWallet --to 0xRecipient --chain xlayer

# Simulate a transaction (dry-run)
onchainos gateway simulate --from 0xYourWallet --to 0xContract --data 0x... --chain xlayer

# Broadcast a signed transaction
onchainos gateway broadcast --signed-tx 0xf86c...signed --address 0xYourWallet --chain xlayer

# Track order status
onchainos gateway orders --address 0xYourWallet --chain xlayer --order-id 123456789

Chain Name Support

The CLI accepts human-readable chain names and resolves them automatically.

Command Index

Cross-Skill Workflows

This skill is the final mile — it takes a signed transaction and sends it on-chain. It pairs with swap (to get tx data).

Workflow A: Swap → Broadcast → Track

User: "Swap 1 ETH for USDC and broadcast it"

1. okx-dex-swap     onchainos swap swap --from ... --to ... --amount ... --chain ethereum --wallet <addr>
       ↓ user signs the tx locally
2. okx-onchain-gateway  onchainos gateway broadcast --signed-tx <signed_hex> --address <addr> --chain ethereum
       ↓ orderId returned
3. okx-onchain-gateway  onchainos gateway orders --address <addr> --chain ethereum --order-id <orderId>

Data handoff:

• tx.data, tx.to, tx.value, tx.gas from swap → user builds & signs → --signed-tx for broadcast
• orderId from broadcast → --order-id param in orders query

Workflow B: Simulate → Broadcast → Track

User: "Simulate this transaction first, then broadcast if safe"

1. onchainos gateway simulate --from 0xWallet --to 0xContract --data 0x... --chain ethereum
       ↓ simulation passes (no revert)
2. onchainos gateway broadcast --signed-tx <signed_hex> --address 0xWallet --chain ethereum
3. onchainos gateway orders --address 0xWallet --chain ethereum --order-id <orderId>

Workflow C: Gas Check → Swap → Broadcast

User: "Check gas, swap for USDC, then send it"

1. onchainos gateway gas --chain ethereum                                    → check gas prices
2. okx-dex-swap     onchainos swap swap --from ... --to ... --chain ethereum --wallet <addr>
       ↓ user signs
3. onchainos gateway broadcast --signed-tx <signed_hex> --address <addr> --chain ethereum
4. onchainos gateway orders --address <addr> --chain ethereum --order-id <orderId>

Operation Flow

Step 1: Identify Intent

• Estimate gas for a chain → onchainos gateway gas
• Estimate gas limit for a specific tx → onchainos gateway gas-limit
• Test if a tx will succeed → onchainos gateway simulate
• Broadcast a signed tx → onchainos gateway broadcast
• Track a broadcast order → onchainos gateway orders
• Check supported chains → onchainos gateway chains

Step 2: Collect Parameters

• Missing chain → recommend XLayer (--chain xlayer, low gas, fast confirmation) as the default, then ask which chain the user prefers
• Missing --signed-tx → remind user to sign the transaction first (this CLI does NOT sign)
• Missing wallet address → ask user
• For gas-limit / simulate → need --from, --to, optionally --data (calldata)
• For orders query → need --address and --chain, optionally --order-id

Step 3: Execute

• Gas estimation: call onchainos gateway gas or gas-limit, display results
• Simulation: call onchainos gateway simulate, check for revert or success
• Broadcast: call onchainos gateway broadcast with signed tx, return orderId
• Tracking: call onchainos gateway orders, display order status

Step 4: Suggest Next Steps

After displaying results, suggest 2-3 relevant follow-up actions:

Present conversationally, e.g.: "Transaction broadcast! Would you like to track the order status?" — never expose skill names or endpoint paths to the user.

CLI Command Reference

1. onchainos gateway chains

Get supported chains for gateway. No parameters required.

onchainos gateway chains

Return fields:

2. onchainos gateway gas

Get current gas prices for a chain.

onchainos gateway gas --chain <chain>

Return fields:

For Solana chains: proposePriorityFee, safePriorityFee, fastPriorityFee, extremePriorityFee.

3. onchainos gateway gas-limit

Estimate gas limit for a transaction.

onchainos gateway gas-limit --from <address> --to <address> --chain <chain> [--amount <amount>] [--data <hex>]

Return fields:

4. onchainos gateway simulate

Simulate a transaction (dry-run).

onchainos gateway simulate --from <address> --to <address> --data <hex> --chain <chain> [--amount <amount>]

Return fields:

5. onchainos gateway broadcast

Broadcast a signed transaction.

onchainos gateway broadcast --signed-tx <tx> --address <address> --chain <chain>

Return fields:

6. onchainos gateway orders

Track broadcast order status.

onchainos gateway orders --address <address> --chain <chain> [--order-id <id>]

Return fields:

Input / Output Examples

User says: "What's the current gas price on XLayer?"

onchainos gateway gas --chain xlayer
# → Display:
#   Base fee: 0.05 Gwei
#   Max fee: 0.1 Gwei
#   Priority fee: 0.01 Gwei

User says: "Simulate this swap transaction before I send it"

onchainos gateway simulate --from 0xYourWallet --to 0xDexContract --data 0x... --chain xlayer --amount 1000000000000000000
# → Display:
#   Simulation: SUCCESS
#   Estimated gas: 145,000
#   Intent: Token Swap

User says: "Broadcast my signed transaction"

onchainos gateway broadcast --signed-tx 0xf86c...signed --address 0xYourWallet --chain xlayer
# → Display:
#   Broadcast successful!
#   Order ID: 123456789
#   Tx Hash: 0xabc...def

User says: "Check the status of my broadcast order"

onchainos gateway orders --address 0xYourWallet --chain xlayer --order-id 123456789
# → Display:
#   Order 123456789: Success (txStatus=2)
#   Tx Hash: 0xabc...def
#   Confirmed on-chain

Edge Cases

• MEV protection: Broadcasting through OKX nodes may offer MEV protection on supported chains.
• Solana special handling: Solana signed transactions use base58 encoding (not hex). Ensure the --signed-tx format matches the chain.
• Chain not supported: call onchainos gateway chains first to verify.
• Node return failed: the underlying blockchain node rejected the transaction. Common causes: insufficient gas, nonce too low, contract revert. Retry with corrected parameters.
• Wallet type mismatch: the address format does not match the chain (e.g., EVM address on Solana chain).
• Network error: retry once, then prompt user to try again later
• Region restriction (error code 50125 or 80001): do NOT show the raw error code to the user. Instead, display a friendly message: ⚠️ Service is not available in your region. Please switch to a supported region and try again.
• Transaction already broadcast: if the same --signed-tx is broadcast twice, the API may return an error or the same txHash — handle idempotently.

Amount Display Rules

• Gas prices in Gwei for EVM chains (18.5 Gwei), never raw wei
• Gas limit as integer (21000, 145000)
• USD gas cost estimate when possible
• Transaction values in UI units (1.5 ETH), never base units

Global Notes

• This skill does NOT sign transactions — it only broadcasts pre-signed transactions
• Amounts in parameters use minimal units (wei/lamports)
• Gas price fields: use eip1559Protocol.suggestBaseFee + proposePriorityFee for EIP-1559 chains, normal for legacy
• EVM contract addresses must be all lowercase
• The CLI resolves chain names automatically (e.g., ethereum → 1, solana → 501)
• The CLI handles authentication internally via environment variables — see Prerequisites step 4 for default values