opentrade-token

What this skill does

# OpenTrade DEX Token Info CLI

5 commands for token search, metadata, detailed pricing, rankings, and holder distribution.

## 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 token search USDC --chains ethereum --trader okx --api v1`
- **Default fallback**: If the API returns no data or is empty, use `--trader okx --api v1`

## Skill Routing

- For real-time prices / K-lines / trade history → use `opentrade-market`
- For swap execution → use `opentrade-dex-swap`
- For transaction broadcasting → use `opentrade-gateway`
- For wallet balances / portfolio → use `opentrade-portfolio`
- For meme token safety (dev reputation, rug pull, bundlers, similar tokens by same dev) → use `opentrade-market`
- For smart money / whale / KOL signals → use `opentrade-market`

## Quickstart

```bash
# Search token
opentrade token search xETH --chains "ethereum,solana"

# Get detailed price info
opentrade token price-info 0xe7b000003a45145decf8a28fc755ad5ec5ea025a --chain xlayer

# What's trending on Solana by volume?
opentrade token toplist --chains solana --sort-by 5 --time-frame 4

# Check holder distribution
opentrade token holders 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee --chain xlayer
```

## Chain Name Support

The CLI accepts human-readable chain names (e.g., `ethereum`, `solana`, `xlayer`) 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` |
| Polygon | `polygon` | `137` |
| Optimism | `optimism` | `10` |
| Avalanche | `avalanche` | `43114` |
| Fantom | `fantom` | `250` |
| Cronos | `cronos` | `25` |
| Gnosis | `gnosis` | `100` |
| Klaytn | `klaytn` | `8217` |
| Aurora | `aurora` | `1313161554` |
| Harmony | `harmony` | `1666600000` |
| Moonbeam | `moonbeam` | `1284` |
| Moonriver | `moonriver` | `1285` |
| Celo | `celo` | `42220` |
| Fuse | `fuse` | `122` |
| OKC | `okc` | `66` |
| Heco | `heco` | `128` |
| Metis | `metis` | `1088` |
| Boba | `boba` | `288` |
| zkSync Era | `zksync` | `324` |
| Polygon zkEVM | `polygon-zkevm` | `1101` |
| Linea | `linea` | `59144` |
| Mantle | `mantle` | `5000` |
| Scroll | `scroll` | `534352` |
| Blast | `blast` | `81457` |

## Command Index

| # | Command | Description |
|---|---|---|
| 1 | `opentrade token search <query>` | Search for tokens by name, symbol, or address |
| 2 | `opentrade token info <address>` | Get token basic info (name, symbol, decimals, logo) |
| 3 | `opentrade token price-info <address>` | Get detailed price info (price, market cap, liquidity, volume, 24h change) |
| 4 | `opentrade token toplist` | Get trending / top tokens |
| 5 | `opentrade token holders <address>` | Get token holder distribution (top 20) |

## Boundary: token vs market skill

| Need | Use this skill (`opentrade-token`) | Use `opentrade-market` instead |
|---|---|---|
| Search token by name/symbol | `opentrade token search` | - |
| Token metadata (decimals, logo) | `opentrade token info` | - |
| Price + market cap + liquidity + multi-timeframe change | `opentrade token price-info` | - |
| Token ranking (trending) | `opentrade token toplist` | - |
| Holder distribution | `opentrade token holders` | - |
| Raw real-time price (single value) | - | `opentrade market price` |
| K-line / candlestick chart | - | `opentrade market kline` |
| Trade history (buy/sell log) | - | `opentrade market trades` |
| Index price (multi-source aggregate) | - | `opentrade market index` |
| Meme token dev reputation / rug pull | - | `opentrade market memepump-token-dev-info` |
| Bundle/sniper detection | - | `opentrade market memepump-token-bundle-info` |
| Similar tokens by same creator | - | `opentrade market memepump-similar-tokens` |

**Rule of thumb**: `opentrade-token` = token discovery & enriched analytics (search, trending, holders, market cap). `opentrade-market` = raw price feeds, charts, smart money signals & meme pump scanning (including dev reputation, rug pull checks, bundler analysis).

## Cross-Skill Workflows

This skill is the typical **entry point** — users often start by searching/discovering tokens, then proceed to swap.

### Workflow A: Search → Research → Buy

> User: "Find BONK token, analyze it, then buy some"

```
1. opentrade-token    opentrade token search BONK --chains solana              → get tokenContractAddress, chain, price
       ↓ tokenContractAddress
2. opentrade-token    opentrade token price-info <address> --chain solana      → market cap, liquidity, volume24H, priceChange24H
3. opentrade-token    opentrade token holders <address> --chain solana         → top 20 holders distribution
4. opentrade-market   opentrade market kline <address> --chain solana --bar 1H → hourly price chart
       ↓ user decides to buy
5. opentrade-dex-swap opentrade swap quote --from ... --to <address> --amount ... --chain solana
6. opentrade-dex-swap opentrade swap swap --from ... --to <address> --amount ... --chain solana --wallet <addr>
```

**Data handoff**:
- `tokenContractAddress` from step 1 → reused in all subsequent steps
- `chain` from step 1 → reused in all subsequent steps
- `decimal` from step 1 or `opentrade token info` → needed for minimal unit conversi