Okx Dex Market

# Shared Chain Name Support

> This file is shared across all onchainos skills.

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

The following 6 chains support **wallet address creation** (i.e., you can generate a wallet address on these chains):

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

> **Note**: The wallet supports interacting with 17+ chains beyond this list (e.g., Polygon, Avalanche, Optimism).
> Run `onchainos wallet chains` for the full list of supported chains.


# Payment Notifications (Market API x402)

Some Market API endpoints may require x402 payment after the free quota is
exhausted. The CLI handles signing automatically once the user is logged in
and surfaces the following events in the response `notifications[]` array.

This document is the canonical source for the 5 event codes, their user-facing
copy, placeholder sources, and the agent handling procedure. It is consumed by
`okx-dex-market`, `okx-dex-token`, `okx-dex-signal`, and `okx-dex-trenches`.

---

## Response Shapes

Every CLI call may include a `notifications[]` field. Two response patterns:

**Non-blocking (informational)**:

```json
{
  "ok": true,
  "data": { /* ... */ },
  "notifications": [{ "code": "...", "data": {} }]
}
```

Print the filled copy once, then display `data` as usual.

**Blocking (first-time charging flip)**:

```json
{
  "confirming": true,
  "notifications": [{
    "code": "MARKET_API_*_OVER_QUOTA",
    "data": {
      "tier": "premium",
      "payment": [
        {
          "amount": "0.0005",
          "asset": "0xUSDG",
          "name": "Global Dollar",
          "symbol": "USDG",
          "network": "X Layer",
          "chainId": 196,
          "payTo": "0xPAYTO",
          "isDefault": false
        },
        {
          "amount": "0.0005",
          "asset": "0xUSDT",
          "name": "Tether USD",
          "symbol": "USDT",
          "network": "X Layer",
          "chainId": 196,
          "payTo": "0xPAYTO",
          "isDefault": true
        }
      ]
    }
  }]
}
```

Each `payment[]` entry is already display-ready: `amount` is a decimal string (not
minimal units), `network` is the chain's human-readable name (falls back to the
raw CAIP-2 string on chain-cache miss), and `chainId` is the numeric EVM chain id
the `onchainos payment default set` CLI expects. `name` carries the full
human-readable asset name (e.g. "Global Dollar"); `symbol` is the short ticker
(e.g. "USDG"). Older servers only returned the ticker in `name` and leave
`symbol` as `""` — render `<symbol> (<name>)` when both are present and
differ, otherwise fall back to `<name>` alone. `isDefault` flags the entry
whose `(asset, network)` matches the user's saved default (at most one per
list); when no default is saved, every entry is `false`.

**Never auto-retry.** The user must always confirm before paying — even when
a default asset is saved, the picker still fires on every first-time tier
charging flip so the user can switch assets or cancel. Once they pick (or
confirm the sole option) and `payment default set` has run, rerun the exact
same command — the CLI will auto-sign the matching accepts entry on the
second call.

---

## Handling Procedure

Before formatting the CLI result:

1. **Check `notifications[]`**. If absent or empty, proceed normally.
2. **For each `notification.code`**:
   - Look up the copy in the code table below.
   - Fill placeholders using the resolution rules.
3. **If `confirming: true` is present on the envelope**:
   - Do NOT auto-retry.
   - Present the filled copy to the user.
   - **If `notifications[].data.payment[]` has ≥ 2 entries**, render them as a
     numbered token list — one line per entry — using the asset label
     (`<symbol> (<name>)` when both are present and differ, else just `<name>`),
     `amo