okx-dex-strategy

What this skill does

# Onchain OS DEX Strategy

4 subcommands that wrap the Agentic Wallet limit-order surface — `create-limit`, `cancel`, `list`, `resume`. SA activation (Trader Mode upgrade / re-upgrade) is performed transparently by the CLI when the BE returns `UPGRADE_REQUIRED`; the skill does not need to expose that detail.

## Pre-flight Checks

> Read `../okx-agentic-wallet/_shared/preflight.md`. If that file does not exist, fall back to `_shared/preflight.md`. Strategy endpoints require an authenticated Agentic Wallet session — confirm login before running any subcommand.

## Display labels & output language (single source of truth)

This section is the **canonical rule** for user-facing strings. Every other section in this skill defers to it.

**Canonical Display labels** — the only strings the agent may surface to the user. The CLI returns these directly (`statusLabel`) for `status`; for `strategyType` the agent looks them up from the §`strategyType` and §`status` tables below.

| Surface | Canonical EN Display labels |
|---|---|
| `strategyType` (4 values) | `Buy Dip` / `Take Profit` / `Stop Loss` / `Buy Above` |
| `status` (9 values) | `Expired` / `Cancelling` / `Cancelled` / `Failed` / `Trading` / `Completed` / `Creating` / `Active` / `Suspended` |

**Translation rule** — match the user's conversation language. Display labels above are canonical English. When the user converses in another language, the agent translates the label at output time to match the conversation language.

**Never** (these rules apply everywhere in this skill):
- mix two languages in one label (pick one — never render the English label and a translation side by side),
- expose the underlying **enum name** (`BUY_DIP`, `CHASE_HIGH`, `COMPLETED`, …) to the user,
- expose the underlying **CLI flag value** (`buy_dip`, `chase_high`, `completed`, `cancelled`, …) to the user,
- pass through the CLI's raw `statusLabel` verbatim when the user is conversing in a non-English language — translate it.

**Notes:**
- CHASE_HIGH renders as **`Buy Above`** in English (not "Chase High").
- SPEEDING_UP (-4) is not a valid filter or display value.

## Boundary vs `okx-dex-swap`

| User intent | Skill |
|---|---|
| "Swap X for Y now" / "Buy 0.5 ETH with USDC" | `okx-dex-swap` (market order, immediate execution) |
| "Buy ETH if it dips to $2000" / "Sell when ETH hits $5000" / "Take profit at X" / "Stop loss at Y" | this skill (price-triggered limit order) |
| "Cancel my pending order" | this skill |
| "What limit orders do I have?" | this skill |

If the venue is named explicitly (Uniswap, PancakeSwap, Raydium, Curve, ...) → re-route to `okx-dapp-discovery`. This skill is for OKX-aggregated limit orders only.

## Command Index

### 1. `onchainos strategy create-limit`

Place a single price-triggered limit order.

```
onchainos strategy create-limit \
  --chain-id <id|alias> \
  --from-token <address> \
  --to-token <address> \
  --amount <decimal-string> \
  --direction <buy|sell> \
  --trigger-price <usd> \
  [--current-price <usd>] \
  [--slippage <value>] \
  [--mev-protection <on|off|default>] \
  [--expires-in <secs>]
```

| Flag | Required | Notes |
|---|---|---|
| `--chain-id` | Y | Chain id or alias: `1`, `solana`, `bsc`, `arbitrum`, `base`, `xlayer` |
| `--from-token` | Y | Sell-side token contract address |
| `--to-token` | Y | Buy-side token contract address |
| `--amount` | Y | Amount of `from_token` to sell (string, no precision loss) |
| `--direction` | Y | `buy` or `sell` (case-insensitive). Strategy type is derived from `--direction` + `--trigger-price` + the current market price; the agent does **not** pass a strategy type explicitly. |
| `--trigger-price` | Y | USD trigger price. Required for strategy type derivation. |
| `--current-price` | N | Current USD price of the comparison token (to-token for `buy`, from-token for `sell`). When omitted the CLI fetches it via `market price`. Pass it to skip the extra HTTP round-trip when the agent already retrieved the price for the confirmation page. |
| `--slippage` | N | Slippage in **percent**. Default `15`. Pass the percent as a plain number (`slippage 20%` → `--slippage 20`). Note `0.05` = 0.05%, NOT 5% — for 5% pass `--slippage 5`. |
| `--mev-protection` | N | Tri-state `on` / `off` / `default` (default = `default`; `default` = BE picks). |
| `--expires-in` | N | Order TTL in seconds. Default 604800 (7 days) — see §Default order expiry. |

**Output (JSON, always — the CLI has no human-format mode):**
```json
{
  "ok": true,
  "data": {
    "orderId": "<id>",
    "status": <int>,
    "statusLabel": "<label>",
    "estimatedWaitTime": <int|null>,
    "eventCursor": "<string|null>"
  }
}
```

**Solana orders return `estimatedWaitTime=0`** — the order is queryable immediately; for all other chains the agent follows §Async wait pattern (fixed 3-second sleep before re-querying).

#### Default order expiry

BE default = **7 days** (`604800` seconds). All other "7 days" mentions in this skill derive from here.

#### Supported chains

Strategy orders are only supported on these 6 chains. Any other chain MUST be rejected upfront by the agent — do not call `create-limit` and do not even open the Step 1 confirmation.

| chainIndex | Name | `--chain-id` aliases |
|---|---|---|
| 1 | Ethereum | `ethereum`, `eth`, `1` |
| 56 | BSC | `bsc`, `56` |
| 196 | X Layer | `xlayer`, `196` |
| 501 | Solana | `solana`, `sol`, `501` |
| 8453 | Base | `base`, `8453` |
| 42161 | Arbitrum | `arbitrum`, `arb`, `42161` |

**Pre-flight rule (agent)**: when the user mentions a chain, resolve it to its chainIndex and check this list. If the chain is **not** in the table (e.g. Polygon `137`, Optimism `10`, Avalanche `43114`, Linea `59144`, Sui `784`, Tron `195`, ...), respond directly with:

> Strategy orders are only supported on Ethereum / BSC / X Layer / Solana / Base / Arbitrum right now. `<requested chain>` is not supported — pick one of these to continue.

Do NOT proceed to Step 1 confirmation. Do NOT call the CLI. The CLI also defends against this (validates against the same 6-chain whitelist before BE), but the agent catching it earlier saves a round trip and gives a clearer message tied to the user's exact phrasing.

#### `strategyType` enum + derivation

`strategyType` is **fully derived inside the CLI** from `(--direction, --trigger-price, current market price)` — there is no `--type` flag and the agent never passes or computes the integer. This single table covers both uses: deriving the **Display label** for the Step 1 confirmation page, and mapping the `strategyType` integer in `list` responses back to a Display label. The Display label is the only user-facing string (see §Display labels & output language).

| strategyType (int) | Enum name | Direction | trigger vs current | Display label | Semantics |
|---|---|---|---|---|---|
| 2 | BUY_DIP | buy | trigger < current | Buy Dip | Buy when price falls to trigger |
| 5 | CHASE_HIGH | buy | trigger ≥ current | Buy Above | Buy when price rises above trigger |
| 3 | TAKE_PROFIT | sell | trigger > current | Take Profit | Sell when price rises to trigger |
| 4 | STOP_LOSS | sell | trigger ≤ current | Stop Loss | Sell when price falls to trigger |

Equality folds into the aggressive side (CHASE_HIGH / STOP_LOSS), matching the CLI.

**Agent flow:**

1. **Parse direction (buy / sell)** from user intent ("buy" / "ape in" / "snap up" → buy; "sell" / "take profit" / "stop loss" / "exit" → sell). Passed verbatim as `--direction <buy|sell>`.
2. **Fetch current price** — call `onchainos market price --chain <chain> --address <token>`, read `data[0].price`. For BUY direction query the **to-token**'s current price; for SELL direction query the **from-token**'s current price. The agent needs this for (a) Step 0 USD-value pre-flight, (b) the Step 1 confirmation page "Trigger Price vs current", and (c) computing the Display label per the table above.
3. **Pass `--current-price <usd>` to the CLI** so it does not re-fetch. (If the age