xlayer-swap-guide

name	xlayer-swap-guide
description	Use this skill BEFORE your first swap or transaction on X Layer, when you get gas-related errors on X Layer, when confused about whether you need OKB for gas, when 'SafeERC20: low-level call failed' or 'another order processing' or 'Pay send-uop failed' errors appear, or when deploying contracts on X Layer. Explains ERC-4337 account abstraction gas model, common error fixes, and X Layer-specific swap patterns.
license	MIT
metadata	{"author":"tantk","version":"1.0.0","homepage":"https://github.com/tantk/agentcfo"}

X Layer Swap & Transaction Guide

Critical knowledge for any agent transacting on X Layer via OnchainOS Agentic Wallet.

Rule #1: You Do NOT Need Gas Tokens

**The Agentic Wallet is an ERC-4337 smart contract wallet with a sponsored paymaster. You never need OKB (or any native token) to pay gas. All gas is covered by the OnchainOS paymaster.**

Do NOT:

• Attempt to acquire OKB/ETH "for gas" before transacting
• Tell the user they need gas tokens
• Assume a failed transaction is a gas issue
• Swap tokens to get native tokens for gas

The OKB dust you may see in a wallet is from swap rounding, not gas payments.

How It Works

Agent calls onchainos swap execute
  → OnchainOS Backend builds a UserOperation
    → ERC-4337 Bundler wraps it in a transaction
      → Paymaster signs gas sponsorship (paymaster pays, not you)
        → EntryPoint contract (0x0000000071727de22e5e9d8baf0edac6f37da032) executes
          → Your smart contract wallet performs the action

The from address on-chain is the bundler, not your wallet. Your wallet is the smart contract that executes the intent.

Verify This Yourself

# Check any Agentic Wallet tx — the 'from' is always a bundler, not your wallet
curl -s "https://rpc.xlayer.tech" -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["TX_HASH"],"id":1}' \
  | python3 -c "
import json,sys
r = json.load(sys.stdin)['result']
print(f'On-chain sender: {r[\"from\"]}')
print(f'This is the bundler/paymaster, NOT your wallet')
"

Error Guide

When a transaction fails, check this table BEFORE assuming it's a gas problem.

Error Message	Actual Cause	Fix
SafeERC20: low-level call failed	Swap route failed — amount too large for liquidity	Try smaller amount (halve it)
another order processing	Previous UserOperation still pending in ERC-4337 mempool	Wait 5-10 seconds, retry
Pay send-uop failed	Bundler rejected the operation — usually a pending tx	Wait and retry
transaction simulation failed	Contract call reverts — check token balance or approval	Verify balance, try smaller amount
estimateGas error	Simulation failed before broadcast — NOT a gas issue	Check the inner error message

**Never retry more than 3 times without changing the parameters.** If 3 retries fail, halve the amount or try a different token pair. Do not loop indefinitely.

X Layer Quick Reference

Item	Value
Chain ID	196
Chain name in CLI	xlayer or okb
Native token	OKB (but you don't need it for gas)
RPC	https://rpc.xlayer.tech
Gas price	~0.02 gwei (extremely cheap)
USDT address	0x779ded0c9e1022225f8e0630b35a9b54be713736
USDC address	0x74b7f16337b8972027f6196a17a631ac6de26d22
USDT/USDC transfers	Zero effective cost (paymaster covers)
EntryPoint (ERC-4337)	0x0000000071727de22e5e9d8baf0edac6f37da032

Swap Best Practices

1. Quote Before Execute

Always get a quote first. If the quote fails, the execute will too.

# Check before committing
onchainos swap quote --from usdt --to okb --readable-amount 5 --chain xlayer
# If this returns data → safe to execute
# If this errors → don't bother with execute

2. Split Large Swaps

Large swaps fail more often than small ones due to DEX routing and liquidity limits. On X Layer with OKB pairs, 2 USDT swaps work reliably but 5+ may fail intermittently.

# Instead of one 10 USDT swap:
onchainos swap execute --from usdt --to okb --readable-amount 2 --chain xlayer --wallet ADDR
onchainos swap execute --from usdt --to okb --readable-amount 2 --chain xlayer --wallet ADDR
onchainos swap execute --from usdt --to okb --readable-amount 2 --chain xlayer --wallet ADDR

3. Token Shortcuts

These work as --from/--to without needing contract addresses:

usdt, usdc, okb, eth, weth, wbtc

For other tokens: onchainos token search --query SYMBOL --chains xlayer

4. Stablecoin Round-Trips Lose Money

USDT → USDC → USDT costs ~$0.004 per $10 in spread. Don't round-trip stablecoins expecting profit.

5. Check "another order processing" Before Retrying

If a swap fails with this error, the previous operation is still in the mempool. Wait, don't spam retries.

Available DEXes on X Layer

The OnchainOS aggregator routes through:

• Uniswap V3
• Uniswap V4
• CurveNG
• PotatoSwap

Available Pools (as of April 2026)

Pool	APY	TVL	Platform
OKB-DOGSHIT	20.5%	$113k	Uniswap V4
OKB-XDOG	8.1%	$252k	Uniswap V4
USDT-OKB	4.9%	$2.3M	Uniswap V3
USDT-xETH	4.3%	$2.0M	Uniswap V3
xSOL-USDT	3.0%	$1.9M	Uniswap V3
USDT-xBTC	2.5%	$2.1M	Uniswap V3
Aave USDT lending	1.6%	—	Aave V3

For More Information

• Swap execution: read okx-dex-swap skill
• Wallet operations: read okx-agentic-wallet skill
• Token search: read okx-dex-token skill
• DeFi pools: read okx-defi-invest skill