opentrade-dex-swap

What this skill does

# OpenTrade DEX Aggregator CLI

5 commands for multi-chain swap aggregation — quote, approve, and execute.

## Pre-flight Checks

Every time before running any `opentrade` 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 opentrade`. If not found, install it:
   ```bash
   curl -sSL https://raw.githubusercontent.com/6551Team/openskills/main/skills/opentrade/install.sh | sh
   ```
   If the install script fails, ask the user to install manually following the instructions at: https://github.com/6551Team/openskills

2. **Check for updates**: Read `~/.opentrade/last_check` and compare it with the current timestamp:
   ```bash
   cached_ts=$(cat ~/.opentrade/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:
     ```bash
     curl -sSL https://raw.githubusercontent.com/6551Team/openskills/main/skills/opentrade/install.sh | sh
     ```
     If a newer version is installed, tell the user and suggest updating their opentrade skills from https://github.com/6551Team/openskills to get the latest features.
3. If any `opentrade` command fails with an unexpected error during this
   session, try reinstalling before giving up:
   ```bash
   curl -sSL https://raw.githubusercontent.com/6551Team/openskills/main/skills/opentrade/install.sh | sh
   ```
4. Find or create a .env file in the project root to override the default API credentials, Load it before performing opentrade operations.
  ```bash
  OPEN_TOKEN=your_token_here
  ```

  Get your API token at: https://www.newsliquid.com/mcp

  **Security warning**: Never commit .env to git (add it to .gitignore) and never expose credentials in logs, screenshots, or chat messages.

## Router Discovery

**IMPORTANT**: If the user has not specified a trading router, you MUST first discover available routers:

```bash
opentrade trade routers
```

**Response format:**
```json
{
  "ok": true,
  "data": [
    {
      "api": "v2",
      "created_at": "2026-03-10 01:15:42",
      "is_active": true,
      "name": "6551dex test",
      "quota_reward": 0,
      "trader": "6551dex",
      "updated_at": "2026-03-10 01:15:42"
    },
    {
      "api": "v1",
      "created_at": "2026-03-03 21:24:34",
      "is_active": true,
      "name": "okx test",
      "quota_reward": 0,
      "trader": "okx",
      "updated_at": "2026-03-03 21:24:34"
    }
  ]
}
```

**Usage:**
- Extract `trader` and `api` from the response
- **MANDATORY**: ALL subsequent `opentrade` commands in this session MUST include `--trader <trader>` and `--api <api>` flags
- Example: `opentrade swap quote --from 0x... --to 0x... --amount 100 --chain ethereum --trader okx --api v1`
- **Default fallback**: If the API returns no data or is empty, use `--trader okx --api v1`

## Skill Routing

- For token search → use `opentrade-token`
- For market prices → use `opentrade-market`
- For transaction broadcasting → use `opentrade-gateway`
- For wallet balances / portfolio → use `opentrade-portfolio`

## Quickstart

### EVM Swap (quote → approve → swap)

```bash
# 1. Quote — sell 100 USDC for OKB on XLayer
opentrade swap quote \
  --from 0x74b7f16337b8972027f6196a17a631ac6de26d22 \
  --to 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee \
  --amount 100000000 \
  --chain xlayer
# → Expected: X.XX OKB, gas fee, price impact

# 2. Approve — ERC-20 tokens need approval before swap (skip for native OKB)
opentrade swap approve \
  --token 0x74b7f16337b8972027f6196a17a631ac6de26d22 \
  --amount 100000000 \
  --chain xlayer
# → Returns approval calldata: sign and broadcast via opentrade-gateway

# 3. Swap
opentrade swap swap \
  --from 0x74b7f16337b8972027f6196a17a631ac6de26d22 \
  --to 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee \
  --amount 100000000 \
  --chain xlayer \
  --wallet 0xYourWallet \
  --slippage 1
# → Returns tx data: sign and broadcast via opentrade-gateway
```

### Solana Swap

```bash
opentrade swap swap \
  --from 11111111111111111111111111111111 \
  --to DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 \
  --amount 1000000000 \
  --chain solana \
  --wallet YourSolanaWallet \
  --slippage 1
# → Returns tx data: sign and broadcast via opentrade-gateway
```

## Chain Name Support

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

| Chain | Name | chainIndex |
|---|---|---|
| XLayer | `xlayer` | `196` |
| Solana | `solana` | `501` |
| Ethereum | `ethereum` | `1` |
| Base | `base` | `8453` |
| BSC | `bsc` | `56` |
| Arbitrum | `arbitrum` | `42161` |

## Native Token Addresses

> **CRITICAL**: Each chain has a specific native token address. Using the wrong address will cause swap transactions to fail.

| Chain | Native Token Address |
|---|---|
| EVM (Ethereum, BSC, Polygon, Arbitrum, Base, etc.) | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` |
| Solana | `11111111111111111111111111111111` |
| Sui | `0x2::sui::SUI` |
| Tron | `T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb` |
| Ton | `EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c` |

> **WARNING — Solana native SOL**: The correct address is `11111111111111111111111111111111` (Solana system program). Do **NOT** use `So11111111111111111111111111111111111111112` (wSOL SPL token) — it is a different token and will cause swap failures.

## Command Index

| # | Command | Description |
|---|---|---|
| 1 | `opentrade swap chains` | Get supported chains for DEX aggregator |
| 2 | `opentrade swap liquidity --chain <chain>` | Get available liquidity sources on a chain |
| 3 | `opentrade swap approve --token ... --amount ... --chain ...` | Get ERC-20 approval transaction data |
| 4 | `opentrade swap quote --from ... --to ... --amount ... --chain ...` | Get swap quote (read-only price estimate) |
| 5 | `opentrade swap swap --from ... --to ... --amount ... --chain ... --wallet ...` | Get swap transaction data |

## Cross-Skill Workflows

This skill is the **execution endpoint** of most user trading flows. It almost always needs input from other skills first.

### Workflow A: Full Swap by Token Name (most common)

> User: "Swap 1 SOL for BONK on Solana"

```
1. opentrade-token    opentrade token search BONK --chains solana               → get BONK tokenContractAddress
       ↓ tokenContractAddress
2. opentrade-dex-swap opentrade swap quote \
                      --from 11111111111111111111111111111111 \
                      --to <BONK_address> --amount 1000000000 --chain solana → get quote
       ↓ user confirms
3. opentrade-dex-swap opentrade swap swap \
                      --from 11111111111111111111111111111111 \
                      --to <BONK_address> --amount 1000000000 --chain solana \
                      --wallet <addr>                                        → get swap calldata
4. User signs the transaction
5. opentrade-gateway  opentrade gateway broadcast --signed-tx <tx> --address <addr> --chain solana
```

**Data handoff**:
- `tokenContractAddress` from step 1 → `--to` in steps 2-3
- SOL native address = `11111111111111111111111111111111` → `--from`. Do NOT use wSOL address.
- Amount `1 SOL` = `1000000000` (9 decimals) → `--amount` param

### Workflow B: EVM Swap with Approval

> User: "Swap 100 USDC for OKB on XLayer"

```
1. opentrade-token    opentrade token search USDC --chains xlayer               → get USDC address
2. opentrade-dex-swap opentrade swap quote --from <USDC> --to 0xeeee...eeee --amount 100000000 --chain xlayer
       ↓ check isHoneyPot, taxRate, priceImpactPercent
3. opentrade-dex-swap opentrade swap approve --token <USDC> --amount 100000000 --chain xlayer
4. User signs the approval transaction
5. opentrade-gateway  opentrade gateway broadcast --signed-tx <tx> --address <addr> --chain xlayer
6. opentrade-dex-swap opentrade swa