opentrade-gateway

What this skill does

# OpenTrade Onchain Gateway CLI

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

## 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 gateway gas --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 swap quote and execution → use `opentrade-dex-swap`
- For market prices → use `opentrade-market`
- For token search → use `opentrade-token`
- For wallet balances / portfolio → use `opentrade-portfolio`
- For transaction broadcasting → use this skill (`opentrade-gateway`)

## Quickstart

```bash
# Get current gas price on XLayer
opentrade gateway gas --chain xlayer

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

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

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

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

## 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` |

## Command Index

| # | Command | Description |
|---|---|---|
| 1 | `opentrade gateway chains` | Get supported chains for gateway |
| 2 | `opentrade gateway gas --chain <chain>` | Get current gas prices for a chain |
| 3 | `opentrade gateway gas-limit --from ... --to ... --chain ...` | Estimate gas limit for a transaction |
| 4 | `opentrade gateway simulate --from ... --to ... --data ... --chain ...` | Simulate a transaction (dry-run) |
| 5 | `opentrade gateway broadcast --signed-tx ... --address ... --chain ...` | Broadcast a signed transaction |
| 6 | `opentrade gateway orders --address ... --chain ...` | Track broadcast order status |

## 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. opentrade-dex-swap     opentrade swap swap --from ... --to ... --amount ... --chain ethereum --wallet <addr>
       ↓ user signs the tx locally
2. opentrade-gateway  opentrade gateway broadcast --signed-tx <signed_hex> --address <addr> --chain ethereum
       ↓ orderId returned
3. opentrade-gateway  opentrade 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. opentrade gateway simulate --from 0xWallet --to 0xContract --data 0x... --chain ethereum
       ↓ simulation passes (no revert)
2. opentrade gateway broadcast --signed-tx <signed_hex> --address 0xWallet --chain ethereum
3. opentrade 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. opentrade gateway gas --chain ethereum                                    → check gas prices
2. opentrade-dex-swap     opentrade swap swap --from ... --to ... --chain ethereum --wallet <addr>
       ↓ user signs
3. opentrade gateway broadcast --signed-tx <signed_hex> --address <addr> --chain ethereum
4. opentrade gateway orders --address <addr> --chain ethereum --order-id <orderId>
```

## Operation Flow

### Step 1: Identify Intent

- Estimate gas for a chain → `opentrade gateway gas`
- Estimate gas limit for a specific tx → `opentrade gateway gas-limit`
- Test if a tx will succeed → `opentrade gateway simulate`
- Broadcast a signed tx → `opentrade gateway broadcast`
- Track a broadcast order → `opentrade gateway orders`
- Check supported chains → `opentrade 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

### Step 3: Execute & Display

- Run the command
- Parse JSON output
- Display human-readable summary (see each command section below)

---

## 1. Supported Chains

List all chains supported by the gateway.

```bash
opentrade gateway chains
```

**Output:**
```json
{
  "code": "0",
  "data": [
    { "chainId": "196", "chainName": "XLayer" },
    { "chainId": "1", "chainName": "Ethereum" },
    { "chainId": "501", "chainName": "Solana" }
  ],
  "msg": ""
}
```

**Display to user:**
- List chain names with IDs
- Highlight commonly used chains

---

## 2. Gas Price

Get current gas price for a specific chain.

```bash
opentrade gateway gas --chain <chain_nam