openclaw/universal-trading

Universal Trading

Execute cross-chain trades with the official Particle Network universal-account-example project.

First-Use Auto Initialization (Default)

When users install this skill and start using it for the first time, auto-run initialization by default.

Use this decision flow:

1. If universal-account-example/.env already exists, treat environment as initialized and continue to trading tasks.
2. If not initialized, run from any directory:

bash {baseDir}/scripts/init.sh new

3. If user explicitly wants to import an existing wallet, run:

bash {baseDir}/scripts/init.sh import <YOUR_PRIVATE_KEY>

After initialization, explicitly tell users:

• private key is stored at universal-account-example/.env under PRIVATE_KEY
• they can use this wallet in the UniversalX frontend: https://universalx.app -> 创建钱包 -> 导入现有钱包

By default, setup auto-binds invite code 666666 after .env is created. It also patches examples/buy-evm.ts to remove usePrimaryTokens restriction.

Optional flags:

# Use existing repo path
bash {baseDir}/scripts/init.sh new --target /path/to/universal-account-example

# Skip smoke test
bash {baseDir}/scripts/init.sh new --skip-smoke

# Disable invite auto-bind
DISABLE_AUTO_INVITE_BIND=1 bash {baseDir}/scripts/init.sh new

Available Operations

Use scripts inside universal-account-example/examples:

• Buy token: buy-solana.ts, buy-evm.ts
• Sell token: sell-solana.ts, sell-evm.ts
• Convert (swap): convert-solana.ts, convert-evm.ts, 7702-convert-evm.ts
• Transfer: transfer-solana.ts, transfer-evm.ts
• Custom transaction calls: custom-transaction-*
• Balance and history: get-primary-asset.ts, get-transactions.ts
• Real-time monitoring: transaction-status-wss.ts, user-assets-wss.ts

For buy operations that need explicit slippage control, use:

• scripts/buy-with-slippage.sh (fixed slippage or dynamic retry)

Trade Status Follow-Up (Required)

After any sendTransaction, do not stop at "transaction submitted". Always return final outcome to user:

1. Capture and show transactionId.
2. Poll status until success or failure:

cd /path/to/universal-account-example
bash {baseDir}/scripts/check-transaction.sh <TRANSACTION_ID> --max-attempts 30 --interval-sec 2

3. Reply with one of:

• SUCCESS (confirmed)
• FAILED (failed on-chain/executor)
• PENDING (not finalized before timeout, include explorer link)

Trade Configuration

| Option | Description | Example | |--------|-------------|---------| | slippageBps | Slippage tolerance (100 = 1%) | 100 | | universalGas | Use PARTI token for gas | true | | usePrimaryTokens | Restrict source/fee primary tokens. Default: do not set (auto select). | [SUPPORTED_TOKEN_TYPE.USDT, SUPPORTED_TOKEN_TYPE.USDC] | | solanaMEVTipAmount | Jito tip for MEV protection (SOL) | 0.01 |

Slippage Controls (Required for Volatile Tokens)

Allow users to choose one of these modes before buy:

1. Fixed slippage only:

cd /path/to/universal-account-example
bash {baseDir}/scripts/buy-with-slippage.sh \
  --chain bsc \
  --token-address 0x0000000000000000000000000000000000000000 \
  --amount-usd 5 \
  --slippage-bps 300

2. Dynamic slippage + auto retry:

cd /path/to/universal-account-example
bash {baseDir}/scripts/buy-with-slippage.sh \
  --chain bsc \
  --token-address 0x0000000000000000000000000000000000000000 \
  --amount-usd 5 \
  --slippage-bps 300 \
  --dynamic-slippage \
  --retry-slippages 300,500,800,1200

3. Solana custom tip (anti-MEV) + retry tips:

cd /path/to/universal-account-example
bash {baseDir}/scripts/buy-with-slippage.sh \
  --chain solana \
  --token-address 6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN \
  --amount-usd 5 \
  --slippage-bps 300 \
  --dynamic-slippage \
  --retry-slippages 300,500,800,1200 \
  --solana-mev-tip-amount 0.001 \
  --retry-mev-tips 0.001,0.003,0.005

Reply with:

• chosen slippage mode and values
• chosen Solana tip settings (if Solana)
• final status (SUCCESS / FAILED / PENDING)
• transactionId and explorer URL when available

Supported Chains

• Solana: CHAIN_ID.SOLANA_MAINNET
• EVM: CHAIN_ID.POLYGON, CHAIN_ID.ARBITRUM, CHAIN_ID.OPTIMISM, CHAIN_ID.BSC, CHAIN_ID.ETHEREUM

Common Token Addresses

• SOL (native): 0x0000000000000000000000000000000000000000
• USDC (Solana): EPjFWdd5AufqSSFqM7BcEHw3BXmQ9Ce3pq27dUGL7C24
• USDT (Solana): Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB

Safety Checklist

1. Validate chain, token address, and amount before creating transactions.
2. Use small size for first live trade.
3. Wrap sendTransaction in try-catch and log transactionId.
4. Prefer your own Particle credentials for production workloads.

Reference Files

• Environment Setup
• API Reference
• Examples