CHANGELOG.md

[English](CHANGELOG.md) | [中文](CHANGELOG.zh-CN.md)

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

---

## [Unreleased]

## [1.5.1] - 2026-11-13

### Added

- **Recurring Buy CLI commands** (`okx bot recurring <sub>`, CLI-only — **no MCP tools**): `create`, `orders [--history]`, `details`, `sub-orders`, `pause`, `restart`, `stop`, `amend-name`, `amend-price-range`, `amend-amount`, `amend-time`, `add-investment`, backed by 12 core `recurring_*` tool specs in the new CLI-only module `bot.recurring`. The module is deliberately not part of `MODULES`, so the MCP tool list (179 tools) and `--modules` are unchanged. `--tdMode` is required (no default and no per-account check in code; the skill guides the choice by `acctLv`: 1 → `cash`, 2 → ask the user to choose `cash` (spot) or `cross` (real leverage), 3 and 4 → `cross` only); `--aiBuilderCode` is accepted on `create`.
- `CLI_ONLY_MODULE_IDS` / `CliOnlyModuleId` exports in `@agent-tradekit/core`; `ToolSpec.module` may now be a CLI-only module.
- CLI: a negative `--timeZone` (e.g. `--timeZone -5`) is now parsed correctly.
- `okx-cex-bot` skill: Recurring Buy command index, write-confirmation checklist (including pause / restart), post-write verification for `add-investment`, a "never retry a failed write on your own; the user decides" rule, DCA vs Recurring Buy routing and `references/recurring-commands.md`.

- **`market_get_trades` / `okx market trades` pagination**: new `history` switch (`--history`) pages through public trades of the last 3 months via `/api/v5/market/history-trades` (max 100 per page), with `type` (`1` tradeId / `2` timestamp), `after` and `before`. No new MCP tool (still 179). Without `history`, behavior is unchanged (latest trades, default 20, max 500).
- **UTC+0 candle bars**: `market_get_candles` (and `okx market candles --bar`) accepts `6Hutc`, `12Hutc`, `1Dutc`, `2Dutc`, `3Dutc`, `1Wutc`, `1Mutc`, `3Mutc`.
- **`market_get_indicator` params contract** (CLI and MCP, 39 indicators + the `boll` alias): omit `params` to use the indicator default (the result reports `appliedParams` / `paramsSource`, the CLI prints `params: … (default)`); if `params` is given it must be complete — fixed-length indicators need exactly the full set (`macd` 3, `kdj` 3, `bb` 2, `supertrend` 2 as `[factor, atrPeriod]`, `stoch-rsi` 4, …), `ma`/`ema`/`rsi`/`wr`/`wma`/`dema`/`tema`/`zlema`/`hma`/`kama` take one or more periods; values are integers (periods 2–365, `bb` multiplier and `supertrend` factor 1–9; `alphatrend` / `halftrend` take any int32 integer). The error carries the signature, default and an example. Other known indicators get no default and no count/range check (malformed values — non-numeric, `null`, overflow — are still rejected); unknown names are still rejected as before. The MCP tool description lists every default.
- CLI: `--params -9,3,3` (leading negative value) is now parsed correctly.

### Changed

- **BREAKING**: `market_get_indicator` / `okx market indicator --params` is stricter. Non-numeric tokens (`[20]`, `12,,9`, `abc`) and a repeated `--params` flag fail instead of silently falling back to defaults; for the 39 indicators of the params contract an incomplete or surplus `params` (e.g. `macd` with 2 values) or an out-of-range value is rejected, and in table mode explicit `--params` that return no values on any timeframe now fail (exit code 1) instead of printing a hint (`--json` is unchanged). When a default was applied and nothing comes back, the hint now says there may not be enough candles. Omitting `params` now applies the indicator default for both CLI and MCP (MCP previously sent no `paramList`, so `ma`/`ema`/`wma`… returned empty). CLI defaults corrected to match the backend: `supertrend` `3,10` (was `10,3`, wrong order), `stoch-rsi` `14,14,3,3`, `keltner` `20,10,20`, `mvwap` `14,14`, `stoch` `14,3`, `aroon` `25`, `trix` `18`; `ma` `5,20,60`, `ema` `5,20`.
- Library: the exported `DEFAULT_INDICATOR_PARAMS` / `getDefaultIndicatorParams` of `@agent-tradekit/core` keep their names but several values changed (see above, e.g. `ma` `[5,20,60]`, `ema` `[5,20]`, `supertrend` `[3,10]`); `params` that is not an array of numbers (a string, a bare number, `null`/`true` items) is now rejected instead of being ignored or coerced.
- **BREAKING**: `market_get_trades` rejects `type`/`after`/`before` unless `history=true` (the recent-trades endpoint does not support pagination), and `limit` above 100 when `history=true`.
- CLI help: `--params` is documented as comma-separated numbers (was `<json>`).

- Synced all skill-pack `metadata.version` fields and pinned `@okx_ai/okx-trade-cli` versions to `1.5.1` for the stable release.

## [1.5.1-beta.2] - 2026-11-10

Beta release: Skill `metadata.version` and pinned CLI install versions remain at `1.5.0` per the stable-release-only policy.

### Added

- **`market_get_trades` / `okx market trades` pagination**: new `history` switch (`--history`) pages through public trades of the last 3 months via `/api/v5/market/history-trades` (max 100 per page), with `type` (`1` tradeId / `2` timestamp), `after` and `before`. No new MCP tool (still 179). Without `history`, behavior is unchanged (latest trades, default 20, max 500).
- **UTC+0 candle bars**: `market_get_candles` (and `okx market candles --bar`) accepts `6Hutc`, `12Hutc`, `1Dutc`, `2Dutc`, `3Dutc`, `1Wutc`, `1Mutc`, `3Mutc`.
- **`market_get_indicator` params contract** (CLI and MCP, 39 indicators + the `boll` alias): omit `params` to use the indicator default (the result reports `appliedParams` / `paramsSource`, the CLI prints `params: … (default)`); if `params` is given it must be complete — fixed-length indicators need exactly the full set (`macd` 3, `kdj` 3, `bb` 2, `supertrend` 2 as `[factor, atrPeriod]`, `stoch-rsi` 4, …), `ma`/`ema`/`rsi`/`wr`/`wma`/`dema`/`tema`/`zlema`/`hma`/`kama` take one or more periods; values are integers (periods 2–365, `bb` multiplier and `supertrend` factor 1–9; `alphatrend` / `halftrend` take any int32 integer). The error carries the signature, default and an example. Other known indicators get no default and no count/range check (malformed values — non-numeric, `null`, overflow — are still rejected); unknown names are still rejected as before. The MCP tool description lists every default.
- CLI: `--params -9,3,3` (leading negative value) is now parsed correctly.

### Changed

- **BREAKING**: `market_get_indicator` / `okx market indicator --params` is stricter. Non-numeric tokens (`[20]`, `12,,9`, `abc`) and a repeated `--params` flag fail instead of silently falling back to defaults; for the 39 indicators of the params contract an incomplete or surplus `params` (e.g. `macd` with 2 values) or an out-of-range value is rejected, and in table mode explicit `--params` that return no values on any timeframe now fail (exit code 1) instead of printing a hint (`--json` is unchanged). When a default was applied and nothing comes back, the hint now says there may not be enough candles. Omitting `params` now applies the indicator default for both CLI and MCP (MCP previously sent no `paramList`, so `ma`/`ema`/`wma`… returned empty). CLI defaults corrected to match the backend: `supertrend` `3,10` (was `10,3`, wrong order), `stoch-rsi` `14,14,3,3`, `keltner` `20,10,20`, `mvwap` `14,14`, `stoch` `14,3`, `aroon` `25`, `trix` `18`; `ma` `5,20,60`, `ema` `5,20`.
- Library: the exported `DEFAULT_INDICATOR_PARAMS` / `getDefaultIndicatorParams` of `@agent-tradekit/core` keep their names but several values changed (see above, e.g. `ma` `[5,20,60]`, `ema` `[5,20]`, `supertrend` `[3,10]`); `params` that is not an array of numbers (a string, a bare number, `null`/`true` items) is now rejected instead of being ignored or coerced.
- **BREAKING**: `market_get_trades` rejects `type`/`after`/`before` unless `history=true` (the recent-trades endpoint does not support pagination), and `limit` above 100 when `history=true`.
- CLI help: `--params` is documented as comma-separated numbers (was `<json>`).

## [1.5.1-beta.1] - 2026-11-02

Beta release: Skill `metadata.version` and pinned CLI install versions remain at `1.5.0` per the stable-release-only policy.

### Added

- **Recurring Buy CLI commands** (`okx bot recurring <sub>`, CLI-only — **no MCP tools**): `create`, `orders [--history]`, `details`, `sub-orders`, `pause`, `restart`, `stop`, `amend-name`, `amend-price-range`, `amend-amount`, `amend-time`, `add-investment`, backed by 12 core `recurring_*` tool specs in the new CLI-only module `bot.recurring`. The module is deliberately not part of `MODULES`, so the MCP tool list (179 tools) and `--modules` are unchanged. `--tdMode` is required (no default and no per-account check in code; the skill guides the choice by `acctLv`: 1 → `cash`, 2 → ask the user to choose `cash` (spot) or `cross` (real leverage), 3 and 4 → `cross` only); `--aiBuilderCode` is accepted on `create`.
- `CLI_ONLY_MODULE_IDS` / `CliOnlyModuleId` exports in `@agent-tradekit/core`; `ToolSpec.module` may now be a CLI-only module.
- CLI: a negative `--timeZone` (e.g. `--timeZone -5`) is now parsed correctly.
- `okx-cex-bot` skill: Recurring Buy command index, write-confirmation checklist (including pause / restart), post-write verification for `add-investment`, a "never retry a failed write on your own; the user decides" rule, DCA vs Recurring Buy routing and `references/recurring-commands.md`.

## [1.5.0] - 2026-10-28

### Added

- **`dca_get_positions` MCP tool and `okx bot dca positions` CLI command**: dedicated entry point for DCA bot position info (avgPx, upl, liqPx, sz, tpPx, slPx, fee). OKX has no separate DCA positions endpoint, so it calls the same `/api/v5/tradingBot/dca/position-details` as `dca_get_order_details` and returns the response as-is; use `dca_get_orders` for strategy-level info (state, pnl, config).

### Changed

- **`dca_get_order_details` is deprecated** (description-only): prefixed with `[DEPRECATED] Use dca_get_positions for position info instead.`. Behavior, parameters and `okx bot dca details` are unchanged.
- Synced all skill-pack `metadata.version` fields and pinned `@okx_ai/okx-trade-cli` versions to `1.5.0` for the stable release.

## [1.4.9] - 2026-10-19

### Added

- **`bot.smartportfolio` module** (8 MCP tools and matching CLI subcommands): complete Smart Portfolio lifecycle management — create, list active and historical orders, get details, stop, amend rebalance parameters, trigger an instant rebalance, browse recommended zones, and get zone backtest data. `deltaRatio` and `portfolioList` are validated and normalized. The module is not in `DEFAULT_MODULES`; load it through `bot.all` or `all`.
- **DCA bot operational management tools**: add margin, reduce margin, and update take-profit for running DCA bots through matching MCP tools and CLI subcommands.
- **Smart Portfolio CLI builder-code support**: `okx bot smart-portfolio create` accepts optional `--aiBuilderCode` and forwards it to `smart_portfolio_create_order`.

### Fixed

- Smart Portfolio order and detail output now uses `pnlRatio`; order output also includes `stgyName`, while the investment currency field remains `investmentCcy`.
- Smart Portfolio CLI `amend-rebalance` now requires and forwards both `deltaRatio` and `interval`.
- DCA margin adjustment rejects non-finite `amt` values; `dca_update_take_profit` no longer exposes the fixed `algoOrdType` parameter; `direction` is optional for `spot_dca` and still required for `contract_dca`.
- DCA margin and copy-trading errors use one table-driven translation helper.

### Changed

- Smart Portfolio active and historical order queries share `smart_portfolio_get_orders`; the CLI uses `orders --history` for historical queries.
- Restructured the `okx-cex-bot` skill by moving Grid Bot, DCA Bot, and workflow guidance into reference files without changing command behavior.
- Synced all skill-pack `metadata.version` fields and pinned `@okx_ai/okx-trade-cli` versions to `1.4.9` for the stable release.

## [1.4.8] - 2026-09-23

### Fixed

- `dca_get_sub_orders` now forwards `after`, `before`, and `limit` when querying orders within a cycle, so pagination can move beyond the first page.
- `okx bot dca sub-orders` now accepts and forwards `--after`, `--before`, and `--limit` for both cycle lists and orders within a cycle.
- DCA tool descriptions clarify that `initOrdAmt` and `safetyOrdAmt` are margin amounts in `contract_dca`, and that `reserveFunds` applies to `spot_dca` only.

### Changed

- Published CLI, MCP, and skill-pack metadata versions are synchronized to `1.4.8`.

## [1.4.7] - 2026-09-14

### Fixed

- `market indicator`, `market oi-history`, `market oi-change`, and `market candles` now reject invalid `--bar` values locally with the supported values. `market candles` treats `1m` and `1M` as distinct values; OI and indicator endpoints accept case-insensitive bar aliases.
- `market pair-spread` now rejects invalid `--bar` values locally; only exact, lowercase `5m` and `15m` are accepted.
- AIGC endpoint errors 41001, 41020, 41030, 50029, and 51000 now provide actionable parameter guidance instead of a generic retry suggestion.

### Changed

- Published CLI, MCP, and skill-pack metadata versions are synchronized to `1.4.7`.

## [1.4.6] - 2026-09-07

### Fixed

- Node 26 proxy compatibility: requests using `proxy_url` or `HTTPS_PROXY` now use a matching undici `fetch` and `ProxyAgent`; update checks use the configured proxy as well.
- `okx market instruments` now forwards `--uly`, `--instFamily`, and `--seriesId`; the MCP tool also accepts `seriesId`.
- Legacy `config.toml` files without a `[profiles]` table no longer cause profile commands to throw.
- Parameter errors with mapped OKX business codes now show actionable guidance instead of a misleading retry suggestion; unmapped codes retain the generic fallback.

### Changed

- Published CLI, MCP, and skill-pack metadata versions are synchronized to `1.4.6`.

## [1.4.5] - 2026-09-01

This stable release removes the discontinued OKX Outcomes integration and strengthens product-boundary routing between CEX event contracts, market data, sentiment, and portfolio queries.

### Added

- `event_browse` now explicitly states that it covers OKX CEX event contracts only, a distinct product from other prediction markets.
- Event-contract workflow guidance now prevents cross-product substitution: if the user's target is absent from `okx event browse` / `series`, report that it is unavailable instead of offering a closest match.

### Changed

- Skill routing guidance now distinguishes price-direction analysis, sentiment rankings, product-filtered positions, and event-contract trading more precisely, reducing cross-product substitutions and overly broad position queries.
- All remaining skill packs' `metadata.version` and pinned `@okx_ai/okx-trade-cli` install version are synced to `1.4.5`.

### Fixed

- `okx news sentiment-rank` help now documents the accepted `--period` and `--sort-by` values instead of numeric placeholders.

### Removed

- **BREAKING** Removed the `okx outcomes` CLI command group and its external binary wrapper. There is no replacement in this package; running `okx outcomes` after upgrade returns "Unknown command".
- **BREAKING** Removed the `skills/okx-outcomes/` skill pack. There is no replacement.

## [1.4.4] - 2026-08-21

This stable release adds per-order AI Builder attribution across the supported CLI order-placement paths, including regular, algo, batch, close-position, event-contract, and bot creation requests.

### Added

- Optional `--aiBuilderCode <code>` flag for supported order-placement commands: spot/swap/futures/option/event place, spot/swap/futures algo place and trail, spot/swap/futures batch place, swap/futures close, and bot grid/DCA create. Valid values are 1-16 alphanumeric chars and override the OKX order `tag` for attribution; invalid values are rejected before the order is submitted and the CLI exits with code 1.

### Changed

- All skill packs' `metadata.version` and pinned `@okx_ai/okx-trade-cli` install version are synced to `1.4.4` per the stable-release skill version sync policy.

### Fixed

- `okx event place` now forwards `--aiBuilderCode` to the order request path.
- `okx swap algo trail` and `okx futures algo trail` now include the configured order tag in the OKX API request body.

## [1.4.3] - 2026-08-20

First stable release of the 1.4.3 line. Code is identical to `1.4.3-beta.3`: OAuth sessions now route requests to the site where the token was issued, site precedence handles empty and conflicting overrides consistently, and the documented US API domain is corrected.

### Changed

- For OAuth users who do not specify a site explicitly, **all** requests (including public market data) now route to the OAuth login site rather than `global`. Public datasets are region-specific, so responses may differ from before. To keep the previous behavior, pass `--site global` (or set `OKX_SITE=global` / toml `site = "global"`). When an explicitly-set site conflicts with the OAuth login site, the CLI prints a warning to stderr and honors the explicit site.
- `--site ""` / `OKX_SITE=""` (empty string) are now ignored and fall through to the next priority level, instead of raising an "Unknown site" error.
- All skill packs' `metadata.version` and pinned `@okx_ai/okx-trade-cli` install version are synced to `1.4.3` per the stable-release skill version sync policy.

### Fixed

- Corrected the US site API base URL shown in the MCP `--site` help text and in the docs from `app.okx.com` (the web/registration domain) to `us.okx.com` (the API domain), matching `OKX_SITES` in code and OKX's regional API-domain requirements. Behavior was already correct; only the help/docs strings were wrong.
- OAuth-authenticated requests now route to the site the OAuth token was issued for. Previously, when no site was set explicitly, all requests fell back to `global` regardless of where the OAuth session was logged in, so a token issued on a non-global site could receive a 401 on private endpoints. The OAuth session site is used as a fallback between toml `site` and the `global` default; it is never persisted. API-key mode and users who set a site explicitly are unaffected.

## [1.4.3-beta.3] - 2026-08-20

Beta release: skill `metadata.version` and the pinned `@okx_ai/okx-trade-cli` install version are intentionally NOT bumped (stable-release-only policy).

### Fixed

- Corrected the US site API base URL shown in the MCP `--site` help text and in the docs from `app.okx.com` (the web/registration domain) to `us.okx.com` (the API domain), matching `OKX_SITES` in code and OKX's regional API-domain requirements. Behavior was already correct (`constants.ts` used `us.okx.com`); only the help/docs strings were wrong.
- OAuth-authenticated requests now route to the site the OAuth token was issued for. Previously, when no site was set explicitly (`--site` / `OKX_SITE` / toml `site`), all requests fell back to `global` (`www.okx.com`) regardless of where the OAuth session was logged in — so a token issued on a non-global site (e.g. EEA) got a 401 on private endpoints like `account balance`. The site is read from the OAuth session (`okx-auth status`) and used as a fallback between toml `site` and the `global` default; it is never persisted. API-key mode and users who set a site explicitly are unaffected.

### Changed

- For OAuth users who do not specify a site explicitly, **all** requests (including public market data) now route to the OAuth login site rather than `global`. Public datasets are region-specific (e.g. a non-global site exposes a slightly smaller instrument set), so responses may differ from before. To keep the previous behavior, pass `--site global` (or set `OKX_SITE=global` / toml `site = "global"`). When an explicitly-set site conflicts with the OAuth login site, the CLI prints a warning to stderr and honors the explicit site.
- `--site ""` / `OKX_SITE=""` (empty string) are now ignored and fall through to the next priority level, instead of raising an "Unknown site" error.

## [1.4.3-beta.1] - 2026-08-10

Beta release of the current `github-main` snapshot. There are no user-facing functional changes since `1.4.2`; this prerelease validates the next `1.4.3` release line.

Beta release: skill `metadata.version` and the pinned `@okx_ai/okx-trade-cli` install version are intentionally NOT bumped (stable-release-only policy).

## [1.4.2] - 2026-07-23

### Fixed

- `okx market indicator <indicator> <instId> --help` now shows `[--list]` in the usage line (placed before `[--limit]`), and the description explains that the command returns the latest value by default; use `--list` + `--limit` for a historical series. Previously `--list` was absent from the help output, causing users to believe `--limit` alone controlled the number of returned values.

## [1.4.1] - 2026-07-21

### Fixed

- `okx bot grid liquidate-price` human-readable output now correctly displays `instId` (backfilled from opts), `direction` (backfilled from opts), and the liquidation price mapped from the real API fields (`longLiqPx` / `shortLiqPx`). Previously all three fields printed as `undefined` because the display layer was reading `item.instId`, `item.liqPx`, and `item.direction`, none of which exist in the API response. For `long` direction the displayed `liqPx` comes from `longLiqPx`; for `short` it comes from `shortLiqPx`; for `neutral` (or no direction) both `longLiqPx` and `shortLiqPx` are shown. `--json` output was already correct and is unchanged.

## [1.4.0] - 2026-07-21

First stable release of the 1.4.0 line. Consolidates all changes accumulated during the 1.3.10 / 1.4.0 beta cycle (see the `[1.3.10-beta.1]` and `[1.4.0-beta.1]` entries below for the original lists): three new contract-grid tools (positions / liquidation-price estimate / close-position) and a fix + hardening of the news tools' `language` handling.

### Added

- `grid_get_positions` MCP tool and `okx bot grid positions` CLI command: query open contract-grid positions (liquidation price, margin ratio, unrealized PnL).
- `grid_get_liquidate_price` MCP tool and `okx bot grid liquidate-price` CLI command: estimate liquidation price for a contract-grid bot before creating it (requires the full intended config — instId/sz/lever/maxPx/minPx/gridNum/direction; runType defaults to '1', triggerStrategy optional; a partial call fails fast listing the missing params instead of hitting a cascade of backend 400s).
- `grid_close_position` MCP tool and `okx bot grid close-position` CLI command: close the remaining open position of a contract-grid bot stopped with `stopType='2'`. The close mode is required with no default (fund-moving) — pass `mktClose=true` / `--mktClose` for a market close, or `mktClose=false` / `--no-mktClose --sz --px` for a limit close; omitting it is rejected on both the MCP and CLI entry points.

### Changed

- News tools' `language` argument now accepts only the canonical enum values `zh-CN` / `en-US`. The previously-tolerated legacy underscore forms (`zh_CN` / `en_US`) are no longer treated specially and fall back to `en_US` (English) — they were never part of the public schema `enum` and were rejected client-side by strict MCP clients anyway. The public enum and the upstream `acceptLanguage` wire value (underscore `zh_CN` / `en_US`) are unchanged.
- All skill packs' `metadata.version` and pinned `@okx_ai/okx-trade-cli` install version synced to `1.4.0` per the stable-release skill version sync policy.

### Fixed

- News tools (`news_get_latest`, `news_get_by_coin`, `news_search`, `news_get_detail`): language is now passed as `acceptLanguage` query parameter (underscore format, e.g. `zh_CN`) instead of the `Accept-Language` request header. The upstream orbit API stopped reading the header; Chinese users were always receiving English content. The public `language` enum (`zh-CN` / `en-US`) is unchanged.

## [1.4.0-beta.1] - 2026-07-17

Beta release: skill `metadata.version` and the pinned `@okx_ai/okx-trade-cli` install version are intentionally NOT bumped (stable-release-only per CLAUDE.md).

### Fixed

- News tools (`news_get_latest`, `news_get_by_coin`, `news_search`, `news_get_detail`): language is now passed as `acceptLanguage` query parameter (underscore format, e.g. `zh_CN`) instead of the `Accept-Language` request header. The upstream orbit API stopped reading the header; Chinese users were always receiving English content. The public `language` enum (`zh-CN` / `en-US`) is unchanged.

## [1.3.10-beta.1] - 2026-07-14

Beta release: skill `metadata.version` and the pinned `@okx_ai/okx-trade-cli` install version are intentionally NOT bumped (stable-release-only per CLAUDE.md).

### Added

- `grid_get_positions` MCP tool and `okx bot grid positions` CLI command: query open contract-grid positions (liquidation price, margin ratio, unrealized PnL).
- `grid_get_liquidate_price` MCP tool and `okx bot grid liquidate-price` CLI command: estimate liquidation price for a contract-grid bot before creating it (requires the full intended config — instId/sz/lever/maxPx/minPx/gridNum/direction; runType defaults to '1', triggerStrategy optional; a partial call fails fast listing the missing params instead of hitting a cascade of backend 400s).
- `grid_close_position` MCP tool and `okx bot grid close-position` CLI command: close the remaining open position of a contract-grid bot stopped with `stopType='2'`. The close mode is required with no default (fund-moving) — pass `mktClose=true` / `--mktClose` for a market close, or `mktClose=false` / `--no-mktClose --sz --px` for a limit close; omitting it is rejected on both the MCP and CLI entry points.

## [1.3.9] - 2026-06-25

First stable release of the 1.3.9 line. Consolidates all changes accumulated during the 1.3.9 beta cycle (see the `[1.3.9-beta.1]` through `[1.3.9-beta.3]` entries below for the full lists): new `tr` (Turkey) site, `okx bot grid sub-orders` pagination parity (`--groupId`/`--after`/`--before`/`--limit`) and the `--pending` flag for querying open sub-orders in both live and demo modes, a fix for the silently-dropped CLI `--site` flag, and 35 new `okx outcomes` eval probes.

### Added

- New `tr` (Turkey) site in the site registry (`https://tr.okx.com`), selectable via `--site tr`, `OKX_SITE=tr`, `site = "tr"` in config.toml, or option `4` in the interactive `okx config init` wizard.
- `okx bot grid sub-orders` now accepts `--groupId`, `--after`, `--before`, and `--limit`, restoring parity with the `grid_get_sub_orders` MCP tool.
- 35 `okx outcomes` eval probes (`eval/probes/outcomes/`), validating LLM-driven tool invocation against live behavior.

### Changed

- `okx bot grid sub-orders` now uses `--pending` to query open/pending sub-orders (works in both live and demo modes), replacing the overloaded `--live` flag. `--live` is retained as a deprecated alias for backward compatibility.
- All skill packs' `metadata.version` and pinned `@okx_ai/okx-trade-cli` install version synced to `1.3.9` per the stable-release skill version sync policy.

### Fixed

- CLI `--site` flag was silently dropped before reaching config resolution, so `--site eea|us|tr` had no effect (requests always hit `www.okx.com`). The flag is now wired through to `loadConfig` on both the main command and `diagnose` paths.

## [1.3.9-beta.3] - 2026-06-25

Beta release: skill `metadata.version` and the pinned `@okx_ai/okx-trade-cli` install version are intentionally NOT bumped (stable-release-only per CLAUDE.md).

### Changed

- `okx bot grid sub-orders` now uses `--pending` to query open/pending sub-orders, replacing the overloaded `--live` flag. `--live` doubled as the global "force live trading mode" switch (mutually exclusive with `--demo`), so pending sub-orders could not be queried in demo mode. `--live` is retained as a deprecated alias for backward compatibility, but prefer `--pending` (which works in both live and demo modes).

## [1.3.9-beta.2] - 2026-06-24

Beta release: skill `metadata.version` and the pinned `@okx_ai/okx-trade-cli` install version are intentionally NOT bumped (stable-release-only per CLAUDE.md).

### Added

- New `tr` site (Turkey) in the site registry — both API base URL and web URL are `https://tr.okx.com`. Selectable via `--site tr`, `OKX_SITE=tr`, `site = "tr"` in config.toml, or option `4` in the interactive `okx config init` wizard.
- `okx bot grid sub-orders` now accepts `--groupId`, `--after`, `--before`, and `--limit`, restoring parity with the `grid_get_sub_orders` MCP tool (which already supported pagination/filtering). Previously the CLI dropped these, so only the first 100 records were reachable.

### Fixed

- CLI `--site` flag was silently dropped before reaching config resolution, so `--site eea|us|tr` had no effect (requests always hit `www.okx.com`); only `OKX_SITE` env var or config.toml `site` worked. The flag is now wired through to `loadConfig` on both the main command and `diagnose` paths.

## [1.3.9-beta.1] - 2026-06-17

Beta release: skill `metadata.version` and the pinned `@okx_ai/okx-trade-cli` install version are intentionally NOT bumped (stable-release-only per CLAUDE.md).

### Added

- Add 35 `okx outcomes` eval probes delivered across 5 phases (`eval/probes/outcomes/`), validating LLM-driven tool invocation against live behavior.

## [1.3.8] - 2026-06-11

First stable release of the 1.3.8 line. Code is identical to `1.3.8-beta.7`. Consolidates all changes accumulated during the 1.3.8 beta cycle (see the `[1.3.8-beta.1]` through `[1.3.8-beta.7]` entries below for the full Added / Fixed / Changed lists): `okx outcomes` CLI wrapper + `okx-outcomes` skill, aggregate balance tool `account_get_balance_all`, issue #200 algo-order fixes (`spot_place_algo_order` `clOrdId`, `closeFraction` full-position close, `algoClOrdId` mapping), Pilot proxy cache TTL expiry + dead-node HTTP failover, `okx market filter` / `okx market indicator` CLI output fixes with default indicator periods, and CI Sonar de-flake.

### Changed

- All skill packs' `metadata.version` and pinned `@okx_ai/okx-trade-cli` install version synced to `1.3.8` per the stable-release skill version sync policy (includes `okx-outcomes`, previously pinned at `1.3.5`).

## [1.3.8-beta.7] - 2026-06-11

> Note: the `okx outcomes` entries below first shipped in `1.3.8-beta.6`, an independent release cut from the `feature_okx_prediction` branch (not from master). This is the first master-based release containing them.

### Added

- **`okx outcomes` CLI wrapper for OKX Outcomes Markets** (YES/NO event contracts; formerly OKX Predictions). Forwards all subcommands to the external `okx-outcomes` Rust binary installed via `curl -fsSL https://raw.githubusercontent.com/okx/outcomes-cli/main/install.sh | sh` (macOS/Linux; Windows users place `okx-outcomes.exe` on `PATH` from the same GitHub Releases). Includes `PATH` discovery with `OKX_OUTCOMES_BIN` override, friendly install hint, and curated `--help` summary. Module is CLI-only (no MCP tools registered) — see `docs/designs/outcomes-wrapper.md`. Authentication is **OAuth sign-in** (`okx outcomes auth login`) for authenticated reads, plus an EIP-712 signing key (`PREDICTIONS_AGENT_PRIVATE_KEY`, normally generated by `okx outcomes setup` and stored in the OS keyring) for on-chain writes. The `auth login --manual` device-code flow (prints `{verificationUri,userCode}` and exits) plus the non-interactive `setup region` / `setup bind` let an agent drive the entire first-time setup end-to-end with no terminal. WebSocket (`ws *`) and `clob cancel-client-order-id` subcommands are intentionally not exposed by the wrapper.
- **`okx-outcomes` skill** guides agents through onboarding (region → OAuth sign-in → wallet bind, with non-TTY/agent hand-off rules), event browsing, account queries (OAuth), live CLOB price / order-book queries, and dry-run-gated trade placement and CTF split/merge/redeem. Trigger list preserves both `prediction`/`预测` and `outcomes` keywords to cover users still using legacy terminology. References split across `setup-auth.md`, `data-commands.md`, `account-commands.md`, `clob-commands.md`, `ctf-commands.md`, and `workflows.md`.

### Fixed

- **`spot_place_algo_order`: add `clOrdId` support for OCO/algo orders** (issue #200). `clOrdId` was missing from both the tool's `inputSchema` and handler, causing it to be silently dropped when placing spot algo orders (e.g. OCO) with a client order ID. `swap_place_algo_order` and `futures_place_algo_order` already exposed `clOrdId` correctly; this fixes the parity gap in the spot equivalent.
- **`swap_place_algo_order` / `futures_place_algo_order`: `closeFraction` full-position-close support for conditional/oco orders** (issue #200). Previously `sz` was unconditionally required, making it impossible to place a full-position-close TP/SL order using `closeFraction`. Now: (1) for `ordType=conditional|oco`, exactly one of `sz` or `closeFraction` must be provided; (2) `closeFraction` must equal `"1"` (only full-position close is supported); (3) `closeFraction` is only valid for `conditional` and `oco` ordTypes - other ordTypes still require `sz`; (4) when `closeFraction` is used with `posSide=net`, `reduceOnly` must be `true`; (5) spot orders do not support `closeFraction` (the field was previously forwarded silently via `buildAlgoConditionalCommonFields` - this is now corrected); (6) `closeFraction` only applies to market TP/SL orders - `tpOrdPx`/`slOrdPx`, when provided, must be `"-1"`.
- **Algo place tools: client order ID now sent as `algoClOrdId`** (issue #200). All six tools posting to `/api/v5/trade/order-algo` (`spot_place_algo_order`, `swap_place_algo_order`, `swap_place_move_stop_order`, `futures_place_algo_order`, `futures_place_move_stop_order`, `option_place_algo_order`) previously sent the client-assigned ID as `clOrdId`, which is not a recognized parameter of the algo-order endpoint (the API expects `algoClOrdId`) - the ID was silently ignored server-side. The tool input schema now exposes `algoClOrdId`; the legacy `clOrdId` input (and the CLI `--clOrdId` flag) is still accepted as an alias and mapped to `algoClOrdId` on the wire. Regular order endpoints (`/api/v5/trade/order` etc.) are unaffected - `clOrdId` remains correct there.

---

## [1.3.8-beta.5] - 2026-06-10

### Fixed

- **Pilot proxy cache TTL expiry** — `resolvePilot()` now ignores stale proxy cache entries. An entry is stale when its age exceeds `min(node.ttl × 1000, 1h)`. Zero or oversized TTL values are capped to 1 hour. `mode=direct` entries are unaffected and never expire.
- **Pilot dead-node HTTP failover** — a Pilot-proxied request that receives a non-2xx response whose body contains no parseable OKX JSON `code` (e.g., HTML 405 from a dead CDN node) is now classified as a dead-node failure. The REST client calls `handleNetworkFailure()` and retries once (GET or `retryOnNetworkError` POST only). Responses that carry a valid OKX JSON error code are not misclassified and surface to the caller unchanged.
- **CI: de-flake the SonarQube test stage** (issue #199). Switched every `node:test` invocation from `node --import tsx/esm --test` (Node 20.6+ only) to `node_modules/.bin/tsx --test` for Node 18 compatibility with the OKG compliance Sonar scanner image. The `--test-timeout` CLI flag is intentionally **not** used: it is Node 20+ only and the Node 18 scanner rejects it (`bad option`, exit 9), which zeroes coverage and fails the quality gate. The actual hang fix is the test hermeticity below, not a timeout flag. As a Node-version-agnostic backstop, the repo `unit-test` CI job now carries a `timeout: 10m` (and `sonar` a `timeout: 15m`) so a hung test fails the job in minutes instead of running to the 1-hour default; per-test hard bounds, if needed, use the Node-18-safe `it(name, { timeout }, fn)` option.
- **CI: make `undici-proxy-bootstrap.test.ts` hermetic** (issue #199). Added `AbortSignal.timeout(5000)` to all four `fetch()` calls in the file; added a file-scope `before`/`after` pair that neutralises ambient `HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY` env vars and captures/restores the global undici dispatcher. The test now passes deterministically on CI runners that carry a corporate proxy environment.

---

## [1.3.8-beta.4] - 2026-06-08

### Added

- **Aggregate balance tool `account_get_balance_all`** (OPRS-360). One-shot snapshot of trading + funding balances with optional cross-account valuation. Calls the server-side aggregate endpoint (`/api/v5/aigc/forward/balance-aggregate`) first and automatically falls back to direct parallel queries (`Promise.allSettled`) when it is unavailable; authentication failures are not retried, and an aggregate response reporting `partialFailure` is returned as-is (no fallback). Partial failure semantics: per-section `available` flag + `meta.partialFailure`. Response `meta` now carries `source` (`aggregate`|`fallback`) and `site` for observability; `requestedAt` is always an ISO 8601 string regardless of path. CLI: `okx account balance-all [ccy] [--accounts trading,funding] [--no-valuation] [--no-aggregate] [--valuationCcy <ccy>]` — `--no-aggregate` forces the parallel path (e.g. when you need the per-account valuation breakdown or a non-USD valuation currency). Skill `okx-cex-portfolio` updated with new command and workflows. Ref: [TD] 聚合balance接口.

---

## [1.3.8-beta.3] - 2026-06-05

### Fixed

- **`okx market filter` empty output in non-`--json` mode** (Bug 1, array-unwrap). The `cmdMarketFilter` text-mode path treated the `aigc/mcp` array-shaped response as a single object, so the human-readable table rendered nothing while `--json` worked. Now unwraps the response with the canonical `(Array.isArray(raw) ? raw[0] : raw)` pattern (matching `cmdMarketOiHistory`), so non-`--json` output is populated.
- **`okx market indicator` silent failure on empty results** (Bug 2, Plan A). When an indicator/timeframe combination returned no values, the render loop `continue`d on every empty timeframe and printed nothing — exit 0 with no output. The CLI now prints an explicit, actionable hint after the loop when nothing was rendered (`No indicator values returned. This indicator may require a period — try --params (e.g. --params 14).`) instead of failing silently.

### Changed

- **`okx market indicator` applies a default period when `--params` is omitted** (Bug 2, Plan B, CLI layer). Omitting `--params` for a period-based indicator (e.g. EMA/MA/WMA/RSI `[14]`, MACD `[12,26,9]`, BB `[20,2]`) now applies a default `paramList` from a table in `packages/core` (single source of truth) so the CLI renders values instead of empty output. **This changes the meaning of omitting `--params` on the CLI**: previously empty, now default-period values. An explicit `--params` still overrides the default. The change is applied **at the CLI render layer only** — the MCP raw-data path (`market_filter` / `market_get_indicator`) is unchanged.
- **Corrected `market_get_indicator` params description** (`indicator.ts:212`). The tool description previously claimed "Omit to use server defaults", which is factually wrong for period-based indicators (the server does not apply default periods). The description no longer makes that false claim.

---

## [1.3.7] - 2026-06-04

Skills-only stable release: the `packages/core·cli·mcp` code is unchanged from `1.3.6`; the `@okx_ai/okx-trade-cli@1.3.7` package is a version-only bump. All functional changes are in the earn-hunter skill.

### Added

- **earn-hunter: Flexible Earn (活期赚币) monitoring** — monitors Simple Earn flexible lending rates for configured currencies (default USDT/USDC). Notifies when APY crosses above threshold (default 8%). Uses threshold-crossing dedup model: one notification per above-threshold period, resets when rate drops below. Activation flow updated to three-way multi-select (Flash/Fixed/Flexible) with independent currency and APY config per type.
- **earn-hunter: macOS LaunchAgent fallback** — when macOS cron daemon (`com.vix.cron`) is not running, activation auto-falls back to a LaunchAgent plist (`~/Library/LaunchAgents/com.okx.earn-hunter.plist`). No sudo required, survives reboot. Pause/Resume/Uninstall support `launchagent` scheduler type.

### Fixed

- **earn-hunter: cron PATH issue + stderr swallowed** — macOS cron runs with `PATH=/usr/bin:/bin`, unable to find node/okx. Added `resolve_bin` + `env.snapshot` for tool path resolution; activation writes `env.snapshot` with absolute paths. `2>/dev/null` replaced with stderr-to-tempfile separation so node's `[UNDICI-EHPA] Warning` no longer pollutes JSON output. Empty `last_error` alerts now show "likely cron PATH issue" guidance.
- **earn-hunter: single feed failure aborted entire scan** — if flash returned OKX Code 8116 (system error), fixed and flexible feeds were never processed. Now continues with whichever feeds succeeded; only counts as scan failure when ALL enabled feeds fail.
- **earn-hunter: transient server error retry** — `retry_cmd` retries up to 3 times (3s interval) for transient errors like Code 8116. Auth errors (401) bail immediately.
- **earn-hunter: CTA hardcoded "Claude Code"** — notification CTA now adapts to channel: session uses interactive CTA ("回复申购金额"), TG/Lark uses generic push CTA without client-specific branding.
- **earn-hunter: flexible diff cleanup test namespace immunity** — removed incorrect `test:` key immunity from flexible cleanup (threshold-crossing semantics differ from flash/fixed offer-existence semantics).
- **earn-hunter: notification channel silently defaulted to session** — activation now always asks user to choose notification channel. Choosing session shows explicit warning about offline blindness.

### Changed

- All skill packs' `metadata.version` and pinned `@okx_ai/okx-trade-cli` install version synced to `1.3.7` per the stable-release skill version sync policy.

---

## [1.3.6] - 2026-06-03

First stable release of the 1.3.6 line. Consolidates all changes accumulated during the 1.3.6 beta cycle (see the `[1.3.6-beta.1]` entry below for the full Added / Fixed list): earn-hunter skill, Ed25519 + SHA-256 skill signature verification, automatic HTTP/HTTPS proxy support, linux-arm64 auth CDN fallback, `earn_get_fixed_earn_products` tool, and MCP tool `title` exposure.

### Changed

- All skill packs' `metadata.version` synced to `1.3.6` per the stable-release skill version sync policy.

---

## [1.3.6-beta.1] - 2026-05-22

### Added

- **earn-hunter skill — OpenClaw in-session cron scheduling**: on OpenClaw, the earn-hunter scheduled scan is now set up inside the conversation via the in-session `cron` agent tool (isolated session + `lightContext`) and delivered back to the chat via cron `announce`, instead of OS crontab. No CLI commands are emitted (the `openclaw cron` CLI path has permission issues). `platform.json` `scheduler.type` is `"openclaw-cron"` on OpenClaw; Claude Code / Hermes keep `"cron"` (OS crontab + curl) and Generic stays `"manual"`.
- **`earn_get_fixed_earn_products` MCP tool** and `okx earn savings fixed-products` CLI command for querying Simple Earn Fixed-term product pool with APR, term, remaining quota, and sold-out status
- **Automatic HTTP/HTTPS proxy support via environment variables**. Set `HTTPS_PROXY` or `HTTP_PROXY` env vars and all undici-backed fetch calls (CLI, MCP server, mcp-gateway) are automatically routed through the proxy. `NO_PROXY` is honored for per-host bypass. Implemented via `EnvHttpProxyAgent` global undici dispatcher in `packages/core/src/runtime/undici-proxy-bootstrap.ts`. No configuration change needed; per-request `proxy_url` config still takes precedence when both are set.
- **Skill signature verification**: `okx skill add` now verifies Ed25519 signature and SHA-256 file integrity before installing a skill, with server-side fallback when local verification cannot proceed. Use `--force` to bypass on verification failure. New command `okx skill verify <name>` re-verifies an installed skill on demand and persists the result to the local registry. New SDK exports: `verifySkillSignature`, `getPublicKey`, `serverSideVerify`, `tryReadMetaJson`, `VerificationResult`, `VerificationStatus`.
- All 163 MCP tools now expose a human-readable `title` at both top-level (`Tool.title`, per MCP spec 2025-06-18) and inside `annotations.title` for backward compatibility, so clients like MCP Inspector render readable labels instead of snake_case names.
- `.env.bak` added to `.gitignore` so local backup env files are never committed.

### Fixed

- **`EnvHttpProxyAgent` experimental warning on every command**: the undici proxy bootstrap registered `EnvHttpProxyAgent` unconditionally at load time, which made Node emit a `[UNDICI-EHPA] ExperimentalWarning` on every CLI command — including local-only ones like `okx skill list` that never make a request. Registration is now gated on the presence of a proxy env var (`HTTPS_PROXY` / `HTTP_PROXY`, upper- or lower-case), so proxy users keep automatic proxy support while everyone else gets a clean, warning-free CLI.
- **linux-arm64: `okx auth status` and `okx auth logout` failed with "All CDN sources failed (HTTP 404)"**. Added a probe-based CDN fallback in `resolveAuthPlatformDir()`: when running on linux-arm64 and CDN returns HTTP 404 for the native `linux-arm64/checksum.json`, the auth installer transparently falls back to the `linux-x64` binary and emits a warning that x86_64 emulation is required. Once a native linux-arm64 binary is uploaded to CDN, the fallback self-deactivates (probe returns HTTP 200 first).
- **`earn savings fixed-redeem` documentation used positional arg instead of `--reqId` flag**: SKILL.md, cli-registry, and savings-commands.md all documented `fixed-redeem <reqId>` (positional), but the CLI router reads `v.reqId` (named flag). Agents following the docs would pass `undefined` as reqId. Now correctly documented as `--reqId <reqId>`.
- **`earn savings rate-history --limit` documentation default was 100, actual code default is 7**: savings-commands.md previously documented the default as 100, but the CLI implementation uses `readNumber(args, "limit") ?? 7`. Now corrected to match the actual default of 7.
- **`earn savings rate-history` and `fixed-products` CLI output used `rate` column but OKX API returns `apr`**: fixed-term offers table always showed empty `rate` column. Now correctly reads `apr` field.

### Changed

- Per-tool `annotations.destructiveHint` and `idempotentHint` are now accurate to MCP spec semantics: 24 additive writes (place_order, transfer, subscribe, redeem) are no longer marked destructive, and 37 destructive idempotent writes (cancel, amend, close, set_leverage) are now marked idempotent. Two 3-in-1 batch routers (`swap_batch_orders`, `spot_batch_orders`) keep the safe write defaults.
- **Non-ASCII cleanup completed -- round 2**. Cleared the remaining 5 residual non-ASCII characters still leaking via TAP output in test `describe`/`it` block names, reducing the count to 0. Completes the series begun in 1.3.5-beta.1.

---

## [1.3.5] - 2026-05-20

Stable rollup of `1.3.5-beta.1` plus a follow-up cleanup. All skill `metadata.version` synced from `1.3.3` to `1.3.5`.

### Added

- **Pair spread tool** (1.3.5-beta.1, !315). `market_get_pair_spread`. Compute spread statistics (mean/stdDev/median/min/max for both absolute and ratio) between two instruments over a configurable lookback window. Supports backtest mode. CLI command: `okx market pair-spread`. No credentials required.

### Fixed

- **CLI startup performance** (1.3.5-beta.1). `okx` no longer pins the Node.js event loop on startup. Four layers: (B0) `OKX_UPDATE_CHECK=false` kill switch; (B1) update checks use the user's configured npm mirror; (A') fetch uses `AbortSignal.timeout(3000)`; (B1.5) failed fetches write a negative-cache entry (1 h TTL).

### Changed

- **`grid_stop_order` / `dca_stop_order` workflow guidance** (1.3.5-beta.1, !305). Tool descriptions now document the two-step close pattern for bots with residual positions.
- **Smartmoney V7 funnel semantics doc sync** (1.3.5-beta.1). Aligned design / module / context-kg / skill / eval docs with the shipped V7 signal funnel. Docs only.
- **Non-ASCII typographic punctuation cleanup**. Two-round sweep replacing em-dash, en-dash, right-arrow, ellipsis with ASCII equivalents across CLI help, tool descriptions, and tests. Round 1 (1.3.5-beta.1) handled the primary surface; round 2 (this release) cleaned 5 residual chars leaking through TAP. No functional change; addresses SonarQube TAP lexer compatibility.
- **Skill `metadata.version` bumped to `1.3.5`** across all 9 skills (`okx-cex-trade`, `okx-cex-market`, `okx-cex-earn`, `okx-cex-bot`, `okx-cex-portfolio`, `okx-cex-skill-mp`, `okx-cex-auth`, `okx-cex-smartmoney`, `okx-sentiment-tracker`). Catches up `1.3.3` → `1.3.5` (skill versions were not bumped in `1.3.4` stable).

---

## [1.3.5-beta.1] - 2026-05-19

### Added

- **Pair spread tool** (!315). `market_get_pair_spread`. Compute spread statistics (mean/stdDev/median/min/max for both absolute and ratio) between two instruments over a configurable lookback window. Supports backtest mode. CLI command: `okx market pair-spread`. No credentials required.

### Fixed

- **CLI startup performance**. `okx` no longer pins the Node.js event loop on startup. Four layers: (B0) `OKX_UPDATE_CHECK=false` kill switch; (B1) update checks use the user's configured npm mirror (`npm_config_registry` env or `.npmrc` walk) instead of hardcoding `registry.npmjs.org`; (A') fetch uses `AbortSignal.timeout(3000)` whose internal unref'd timer prevents infinite event-loop hang; (B1.5) failed fetches write a negative-cache entry (1 h TTL) so repeated cold-starts on unreachable networks skip the fetch entirely.

### Changed

- **`grid_stop_order` / `dca_stop_order` workflow guidance** (!305). Tool descriptions now document the two-step close pattern for bots with residual positions: stopping with `stopType="2"` puts the bot into `no_close_position` (strategy paused, position still open); calling stop again with `stopType="1"` then closes the remaining position. Applies to both grid and DCA (contract and spot variants). Empirically verified on OKX demo API.
- **Smartmoney V7 funnel semantics doc sync.** Aligned `docs/designs/smartmoney.md`, `docs/modules/smartmoney.md`, `context-kg/business/06-leaderboard-smartmoney-api.md`, `skills/okx-cex-smartmoney/references/signal-commands.md`, and `eval/README.md` with the shipped V7 signal funnel. Docs only.
- Replaced non-ASCII typographic punctuation (em-dash, en-dash, right-arrow, ellipsis) with ASCII equivalents in CLI help text, tool descriptions, and CLI output placeholders. No functional change; addresses SonarQube TAP lexer compatibility.

> Note: `market_get_pair_spread` was historically tagged in `1.3.4-beta.2` but was deliberately excluded from the `v1.3.4` stable release tag (which is anchored at `cd99d487`, the `1.3.4-beta.1` bump commit). It ships in `1.3.5-beta.1` instead.

---

## [1.3.4] - 2026-05-13

Stable rollup of `1.3.4-beta.1` only. The `1.3.4-beta.2` line below is retained as historical record but its content (`market_get_pair_spread`) does NOT ship in the `v1.3.4` tag — see `## [1.3.5-beta.1]` above.

### Added

- **Economic calendar tools** (1.3.4-beta.1, !298). `news_get_economic_calendar` + `news_list_calendar_regions`. Query macro-economic events (GDP, CPI, NFP, FOMC, etc.) with region/importance filters and configurable time-window controls. CLI commands: `okx news economic-calendar`, `okx news list-regions`. Skill `okx-sentiment-tracker` updated with calendar workflow guidance.

---

## [1.3.4-beta.2] - 2026-05-12

### Added

- **Pair spread tool** (`market_get_pair_spread`). Compute spread statistics (mean/stdDev/median/min/max for both absolute and ratio) between two instruments over a configurable lookback window. Supports backtest mode. CLI command: `okx market pair-spread`. No credentials required.

## [1.3.4-beta.1] - 2026-05-12

### Added
- **Economic calendar tools** (`news_get_economic_calendar`, `news_list_calendar_regions`). Query macro-economic events (GDP, CPI, NFP, FOMC, etc.) with region/importance filters and time-window controls. CLI commands: `okx news economic-calendar`, `okx news list-regions`. Skill `okx-sentiment-tracker` updated with calendar workflow guidance.

## [1.3.3] - 2026-05-08

Stable rollup of `1.3.3-beta.1` → `1.3.3-beta.3`. See per-beta sections below for full implementation detail.

### ⚠ BREAKING

- **`smartmoney` module redesign — no compat shim** (1.3.3-beta.1, !304). MCP/CLI surface fully rewritten for AI-agent disambiguation: 8 → 10 atomic tools (`get_traders_by_filter`, `get_performance_by_trader`, `get_trader_orders_history`, `get_trader_positions`, `get_trader_positions_history`, `get_signal_overview_by_filter`, `get_signal_overview_by_trader`, `get_signal_trend_by_filter`, `get_signal_trend_by_trader`, `search_trader`). Old tool/parameter/field names removed. Arrays replace CSV strings for `authorIds` / `instCcyList`. Pool-filter rename (`pnl`/`winRate`/`asset` → `minPnl`/`minWinRate`/`minAum`). Output field renames (`winRatio` → `winRate`, `maxRetreat` → `maxDrawdown`). Full migration guide: [`docs/designs/smartmoney.md`](docs/designs/smartmoney.md).

### Added

- **Windows named-pipe OAuth token retrieval for `okx auth`** (`packages/core/src/auth/`, !310). Eliminates the WSL/elevated-privilege requirement on Windows; tokens are fetched via a per-invocation named pipe (`\\.\pipe\okx-auth-<256-bit-random>`) instead of fd-3 forwarding.
- **`--tpLevel` multi-tier take-profit flag (Phase 3b)** (!292, #183). Repeatable on `okx {swap,spot,futures} place` and `algo place` for independent TP tiers. CLI-only (not exposed in MCP / skill workflows).
- **Phase 3a+c CLI power-user flags** (!291, #182). Six new optional flags: `--tpTriggerRatio` / `--slTriggerRatio` (ratio-based TP/SL triggers), `--closeFraction` (partial-position close), `--tradeQuoteCcy` (SPOT quote currency), `--banAmend` (disable OKX auto-amend), `--pxAmendType` (price out-of-range correction). CLI-only.
- **LLM eval probe coverage 17/17 MCP modules** (`eval/probes/`, !303). All modules now have trace-based probes (`findToolCall`); CI gate `eval-probe-check` enforces full coverage.

### Fixed

- **Log disk usage bounded with retention sweep** (`packages/core/src/logger.ts`, !312). Startup sweep prunes `~/.okx/logs/` files beyond the configured retention window — prevents unbounded disk growth on long-running installations.
- **`event_browse` concurrent fetch cap** (`packages/core/src/tools/event-trade.ts`, !300, #146). Semaphore caps concurrent market-fetches at 8 (OKX 20-req window minus 12 retry buffer). Switched to `Promise.allSettled` so a single failing series no longer aborts the browse.
- **`cmdAuthRemove` permission-denied error handling** (`packages/cli/src/commands/auth.ts`, !299, #159). Added integration test coverage for the EACCES path (`errorLine` in text mode, `{status:"failed",error:<msg>}` in JSON mode, `process.exitCode = 1`).
- **Layered Architecture diagram corrected** (`ARCHITECTURE.md`, `ARCHITECTURE.zh-CN.md`, !296, #185). Replaced the single-path waterfall (which mislabeled `packages/mcp/src/index.ts` as "CLI entry") with a two-binary diagram showing `okx-trade-mcp` and `okx` as independent binaries on top of `@agent-tradekit/core`.

### Changed

- **`smartmoney` schema: `sortBy` / `period` / `granularity` now required** (1.3.3-beta.2). All leaderboard + signal tools mark `sortBy` and `period` as `required`; `signal-trend-*` also requires `granularity`. Handlers inject defaults explicitly so MCP and CLI paths are deterministic. Compat: callers that already passed these params are unaffected.
- **`smartmoney` signal-* tools: clarify linear-only scope** (1.3.3-beta.2, SIG-01). `signal-*` tools and skill docs now state that `instCcyList` / `instCcy` aggregate USDT/USDS-margined contracts only — coin-margined positions are silently excluded by upstream. Docs only.
- **`linux-arm64` pilot binary routes to native arm64** (`packages/core/src/pilot/installer.ts`, !295). Removes the previous `linux-arm64 → linux-x64` qemu/binfmt emulation fallback.
- **Smart Money skill refreshed** (`skills/`, !294). Trigger phrases, workflow guidance, and tool surface descriptions updated for the new `smartmoney_*` tool set.
- **`context-kg/` mapping sections updated** (`context-kg/business/06-leaderboard-smartmoney-api.md`, `07-dcd-api.md`, `08-dca-api.md`, !302, #187). Rewrote "Mapping to…" sections to match the shipped tool surface; added "Backlog (not yet wrapped)" for V2-only upstream paths.

---

## [1.3.3-beta.3] - 2026-05-08

### Added

- **Windows named-pipe token retrieval for `okx auth`** (`packages/core/src/auth/`): On Windows hosts, OAuth bearer tokens are now fetched via a named pipe instead of fd3 forwarding, removing the requirement for WSL or elevated privileges. (!310)

- **`--tpLevel` multi-tier take-profit flag (Phase 3b)**: Pass `--tpLevel` multiple times on `okx {swap,spot,futures} place` and `algo place` to set independent TP tiers (e.g. `--tpLevel "px:78000,sz:0.5,kind:limit" --tpLevel "px:81000,sz:0.5,kind:market"`). Valid keys: `px`, `sz`, `kind`, `triggerPx`, `triggerPxType`, `amendPxOnTrigger`, `clOrdId`. Combining `--tpLevel` with legacy `--tpOrdPx`/`--tpTriggerPx` is rejected at the CLI layer. Not exposed in MCP tool descriptions or skill workflows (intentional). (!292, #183)

- **Phase 3a+c CLI power-user flags**: Six new optional flags — `--tpTriggerRatio`/`--slTriggerRatio` (ratio-based TP/SL triggers), `--closeFraction` (partial-position close, mutually exclusive with `--sz`), `--tradeQuoteCcy` (SPOT quote currency selection), `--banAmend` (disable OKX auto-amend on SPOT market orders), `--pxAmendType` (price out-of-range correction control). Applies to `okx {swap,spot,futures} place` and `okx {swap,futures} algo place`. No MCP or skill exposure (intentional). (!291, #182)

- **LLM eval probe coverage completed to 17/17 MCP modules** (`eval/probes/`): All remaining modules now have probe files at `eval/probes/<module>/tier2-<tool_name>.live.test.ts` using trace-based assertions (`findToolCall`). Full-suite 17/17 module coverage is now enforced by the CI `eval-probe-check` gate. (!303)

### Fixed

- **Log disk usage bounded with retention sweep** (`packages/core/src/logger.ts`): A startup sweep now prunes log files in `~/.okx/logs/` beyond the configured retention window, preventing unbounded disk growth on long-running installations. Previously, log files accumulated indefinitely. (!312)

- **`event_browse` concurrent fetch cap** (`packages/core/src/tools/event-trade.ts`, `event-helpers.ts`): Replaced unbounded `Promise.all` with a semaphore capped at 8 concurrent market-fetch requests (OKX window is 20 req; 12 reserved as buffer for retries). Switched to `Promise.allSettled` so a single failing series no longer aborts the entire browse — series with no active contracts are silently skipped. (!300, #146)

- **`cmdAuthRemove` permission-denied error handling** (`packages/cli/src/commands/auth.ts`): The existing error path when `removeAuthBinary()` throws (e.g. EACCES) now has integration test coverage: `errorLine` is emitted in text mode, `{status:"failed",error:<msg>}` in JSON mode, and `process.exitCode` is set to `1` in both cases with no rethrow. (!299, #159)

- **Layered Architecture diagram** (`ARCHITECTURE.md`, `ARCHITECTURE.zh-CN.md`): Replaced the single-path waterfall diagram — which incorrectly labeled `packages/mcp/src/index.ts` as "CLI entry" — with a two-binary diagram showing `okx-trade-mcp` and `okx` as independent binaries that both import from the shared `@agent-tradekit/core` SDK. (!296, #185)

### Changed

- **`linux-arm64` pilot binary now routes to native arm64** (`packages/core/src/pilot/installer.ts`): The previous `linux-arm64 → linux-x64` stop-gap fallback is removed. The platform now routes directly to the native arm64 binary published at `/upgradeapp/tools/pilot/linux-arm64/okx-pilot`, eliminating qemu/binfmt emulation overhead on ARM64 Linux hosts. (!295)

- **Smart money skill refreshed** (`skills/`): Updated trigger phrases, workflow guidance, and tool surface descriptions to reflect the current `smartmoney_*` tool set and signal semantics. (!294)

- **`context-kg/` mapping sections updated** (`context-kg/business/06-leaderboard-smartmoney-api.md`, `07-dcd-api.md`, `08-dca-api.md`): Rewrote the "Mapping to…" sections in all three docs to match the shipped tool surface: `06` now lists the 5 shipped `smartmoney_*` tools; `07` lists the 6 flat `dcd_*` tools with bundling-decision notes; `08` lists the 5 unified `dca_*` tools plus a new "Backlog (not yet wrapped)" subsection for the 10 V2-only upstream paths. (!302, #187)

---

## [1.3.3-beta.2] - 2026-05-08

### Docs — `smartmoney` signal tools: clarify linear-only scope (SIG-01)

`signal-*` tools and skill docs now state that `instCcyList` / `instCcy` aggregate **USDT/USDS-margined contracts only** — coin-margined (`-USD-SWAP` / `-USD-DELIVERY`) positions are silently excluded by upstream. No behavior change.

### Changed — `smartmoney` schema: `sortBy` / `period` / `granularity` now required

- All leaderboard + signal tools mark `sortBy` and `period` as `required`; `signal-trend-*` also requires `granularity`. Fixes silent reliance on backend defaults (e.g. `period` documented as `90` but actually returning lifetime cumulative).
- `performance-by-trader`, `signal-overview-by-trader`, `signal-trend-by-trader` newly accept `sortBy` + `period` (T2 was period-only).
- Handlers inject defaults explicitly (`sortBy=pnl`; leaderboard `period=90` / signal `period=7`; trend `granularity=1h`) so MCP and CLI paths are deterministic.

Compat: callers that already passed these params or relied on documented defaults are unaffected.

## [1.3.3-beta.1] - 2026-05-06

### ⚠ BREAKING — `smartmoney` module redesign

Smart Money MCP/CLI surface is fully rewritten for AI-agent disambiguation. **No compat shim** — old tool/parameter/field names are removed. Full rationale in [`docs/designs/smartmoney.md`](docs/designs/smartmoney.md).

CLI parity: each CLI command is the MCP tool name minus `smartmoney_` and `get_`, snake → kebab (e.g. `smartmoney_get_traders_by_filter` ↔ `okx smartmoney traders-by-filter`). The `--authorIds` / `--instCcyList` flags accept comma-separated input (CLI splits to array at the boundary).

#### Tool surface (8 → 10 atomic tools)

| Old (1.3.2) | New | Notes |
|---|---|---|
| `get_traders` (pool-filter mode) | `get_traders_by_filter` | `limit` default 100 → 10 |
| `get_traders` (authorIds mode) | `get_performance_by_trader` | direct lookup, no pool filter |
| `get_trader_records` | `get_trader_orders_history` | aligns with `*_get_orders` family |
| `get_trader_positions` | `get_trader_positions` | name unchanged |
| `get_trader_position_history` | `get_trader_positions_history` | pluralized |
| `get_signal` (pool-filter mode) | `get_signal_overview_by_filter` | `ts` removed; `topInstruments` (default 20) subsumes "top-coin overview" |
| `get_signal` (authorIds mode) | `get_signal_overview_by_trader` | tighter input — pool filters removed (use `_by_filter` for tier discovery) |
| `get_signal_history` | `get_signal_trend_by_filter` | renamed for symmetry with `_by_trader` sibling |
| `get_overview`, `get_top_coin_signals`, `get_trader_detail` | _(removed)_ | superseded; `_trader_detail` was non-atomic |
| _(new)_ | `search_trader` | nickname → authorId resolution (≤10 matches, follower-count DESC) |
| _(new)_ | `get_signal_trend_by_trader` | single-asset time-series restricted to authorIds |

#### Input changes

- **Arrays replace CSV strings** for `authorIds` and `instCcyList` (typed arrays catch shape mistakes earlier than runtime CSV parsing).
- **Leaderboard pool-filter rename** to disambiguate from signal-side `*Tier` enums: `pnl` → `minPnl`, `winRate` → `minWinRate`, `asset` → `minAum` (`maxDrawdown` unchanged). Signal-side keeps `pnlTier` / `winRateTier` / `maxDrawdownTier` / `aumTier`.
- **Time anchors split by family**: leaderboard uses `updateTime` (12-digit `yyyyMMddHHmm` UTC+8); signal-trend uses optional `asOfTime` (10-digit `yyyyMMddHH` UTC, defaults to current hour); signal-overview takes no time input. `ts` and `dataVersion` removed as inputs everywhere.
- **`signal_*_by_trader` no longer takes pool filters** — pool-filter axis is exclusive to `_by_filter` siblings, see [`docs/designs/smartmoney.md`](docs/designs/smartmoney.md) §13.
- **Trader-side `instCcy` → `instId`** on `_trader_positions` / `_positions_history` / `_orders_history`: accepts full `instId` or bare base ccy; handler extracts base.
- **Signal pool-filter `period`** (3/7/30/90, default 7) now exposed on every signal-side tool (previously leaderboard only).
- **`lmtNum` max 500 → 2000** on signal-overview tools.

#### Output changes

- **Leaderboard fields renamed** (everywhere): `winRatio` → `winRate`, `maxRetreat` → `maxDrawdown`, `dataVersion` → `updateTime` (leaderboard-only; signal items keep `dataVersion` at bucket level).
- **Signal-overview reshaped to nested groups** per OpenAPI `/overview` spec — outer `ccy` plus `notional` / `longShortRatio` / `winRate` objects. Old flat fields (`vs1h` / `vs24h` / `vs7d`, top-level `longNotionalUsdt`, etc.) removed.
- **Added** `direction` (derived `"long" | "short"` from `posSide` + sign of `pos`) and `upl` (unrealized PnL, quote ccy) on `_trader_positions`.
- **Removed** `topNUsed`, `currentPrice`, `priceChange24h`, `fundingRate`, `openInterest`, `longShortAccountRatio`, `ts` from signal/overview output.

#### Other

- MCP tool annotations (`readOnlyHint` / `idempotentHint` / `openWorldHint`) on every tool.
- Actionable error messages replace opaque `sCode` strings.

#### Migration

```ts
// Multi-coin overview — instCcyList still works; no time input
smartmoney_get_signal_overview_by_filter({ instCcyList: ["BTC", "ETH"] })

// Single-coin signal-history → signal-trend; asOfTime is optional
smartmoney_get_signal_trend_by_filter({ instCcy: "BTC", granularity: "1h", limit: 24 })

// trader_detail composite removed → fan out 3 atomic calls in parallel
Promise.all([
  smartmoney_get_performance_by_trader({ authorIds: ["X"] }),
  smartmoney_get_trader_positions({ authorId: "X" }),
  smartmoney_get_trader_orders_history({ authorId: "X", limit: 50 }),
])
```

---

### Added

- **Windows support for OAuth token retrieval** (`packages/core/src/auth/binary.ts`). `execAuthToken()` now dispatches on `process.platform`: Unix keeps the existing fd-3 channel, while Windows creates a per-invocation named pipe `\\.\pipe\okx-auth-<256-bit-random>`, listens on it, and passes the name to the child via the `OKX_AUTH_TOKEN_PIPE` environment variable. The `okx-auth` Rust binary opens that pipe with `CreateFileW(FILE_GENERIC_WRITE, OPEN_EXISTING)`, writes the access token, and closes — signalling EOF to the parent. The pipe name is enforced to start with `\\.\pipe\okx-auth-` (the binary rejects arbitrary targets), and `OKX_AUTH_TOKEN_PIPE` is scrubbed by the child after read so it never leaks to grandchildren. Both platforms share the same exit-code → typed-error mapping (`finalizeToken` helper), so error messages are identical regardless of OS. Windows users can now complete the full `okx auth login` → token-backed REST flow end-to-end; previously the binary spawned successfully but the consumer's fd-3 read found nothing because Windows doesn't inherit POSIX file descriptors. The new code path is covered on POSIX hosts via UNIX-domain-socket substitution (`net.createServer` abstracts the transport), so CI does not require a Windows runner.

### Fixed

- **`event_browse` concurrency cap** (`packages/core/src/tools/event-trade.ts`, `event-helpers.ts`): replaced unbounded `Promise.all` with a semaphore-based `withConcurrency` helper capped at `MAX_CONCURRENT_MARKET_FETCHES = 8` concurrent market-fetch requests (rate limit window is 20 req; 12 requests kept as buffer for retries and other calls in the same window: `20 - 12 = 8`). Also switched from `Promise.all` to `Promise.allSettled` semantics so a single failing series fetch no longer aborts the entire browse — series with no active contracts are silently skipped and all successful series are still returned. Closes #146.

- **`cmdAuthRemove` error handling** (`packages/cli/src/commands/auth.ts`): the existing try/catch around `removeAuthBinary()` now has test coverage. Added two unit tests to `packages/cli/test/auth.test.ts` that verify when `removeAuthBinary()` throws (e.g. permission denied / EACCES): (a) `errorLine` is called with the error message in text mode, (b) JSON output `{status:"failed", error:<msg>}` is produced in json mode, and (c) `process.exitCode` is set to `1` in both cases with no rethrow to the caller. Closes #159.

- **Layered Architecture diagram** (`ARCHITECTURE.md`, `ARCHITECTURE.zh-CN.md`): replaced the single-path waterfall diagram that incorrectly labeled `packages/mcp/src/index.ts` as "CLI entry" with a two-binary diagram showing `okx-trade-mcp` and `okx` as independent binaries that both import from `@agent-tradekit/core` (shared SDK). Closes #185.
- **`docs/faq.md` — API key storage answer**: added a clarifying sentence that the CLI (`okx`) and the MCP server (`okx-trade-mcp`) each read `~/.okx/config.toml` independently with no dependency between them.

### Changed (other)

- **`linux-arm64` hosts now use native arm64 pilot binary** (`packages/core/src/pilot/installer.ts` `PLATFORM_MAP` + `scripts/postinstall-notice.js`). The previous `linux-arm64 → linux-x64` fallback (introduced as a stop-gap when no native binary was on CDN) downloaded the x64 binary and ran it via qemu/binfmt emulation. The native arm64 binary has been published at `/upgradeapp/tools/pilot/linux-arm64/okx-pilot` (verified 2026-04-29); routing to it directly removes the emulation overhead — faster startup, lower CPU.

- **`context-kg/` mapping sections refreshed for 06/07/08** (`context-kg/business/06-leaderboard-smartmoney-api.md`, `07-dcd-api.md`, `08-dca-api.md`): The "Mapping to …" sections in all three docs have been rewritten to reflect the as-shipped tool surface. `06` now lists the 5 shipped `smartmoney_*` tools (replacing the pre-implementation 7-tool `market_*` proposal) with a note that `feat/smartmoney-fix` is in flight for a further redesign. `07` now lists the 6 flat `dcd_*` tools with an explanation of the deliberate quote→trade and redeem-quote→redeem bundling decisions. `08` now lists the 5 unified `dca_*` tools that key off `algoOrdType: spot_dca | contract_dca`, plus a new "Backlog (not yet wrapped)" subsection listing the 10 V2-only upstream API paths not yet implemented. Closes #187.

---

## [1.3.2] - 2026-04-27

### Changed

- **`skills/okx-cex-auth/SKILL.md` — strict display templates + wait-for-signal flow**:
  - Login initiation: upgraded from "example reply format" to strict CN/EN templates with four mandatory fields (`site`, `verificationUri`, `userCode`, `expiresIn`). Template wording is now normative — agents must not abbreviate, reword, reorder, or translate.
  - Polling removed: agents no longer auto-poll `okx auth status --json` every 5–10 s. They now wait for the user to signal completion (e.g. "done", "好了"), then run `auth status --json` once to verify.
  - Login success display: restricted to `site` + `scopes` only. Explicit negative list forbids surfacing `expiresAt` / `ttl` (these are access-token TTL, not OAuth session lifetime — tokens auto-refresh transparently) and `profile` (internal routing field). If asked about session longevity, agents must use the fixed phrase "Session stays active as long as you use the CLI periodically." and never quote a number.
  - Cross-section consistency: Step 0.3 table and Login Status Check table updated to reference the new strict templates and wait-for-signal semantics.

### Added

- **`eval/probes/` infrastructure + CI gate `eval-probe-check`** (MR !303). Every new/modified MCP tool now requires a probe at `eval/probes/<module>/tier2-<tool_name>.live.test.ts`; the CI job is `allow_failure: false` and runs on every merge_request_event. Probes use trace-based assertions (`findToolCall(trace, { commandPatterns })`) on the agent's `tool_use` blocks parsed from `anthropic-payload.jsonl` — they verify the LLM picked the right `okx <module> <subcommand>` with the right parameters, regardless of upstream API auth result. **Module coverage to date**: 12/17 modules (28 contributor probes covering market, spot, swap, futures, option, account, event, news, smartmoney, skills, bot.{grid,dca}, earn.{savings,onchain,dcd,flash}). Deferred: `earn.autoearn` (placeholder dir only), `earn.fixed` (no dir yet). See [`eval/README.md`](eval/README.md) for the probe skeleton + CLI command pattern recipe table.
- **Phase 3b CLI power-user flag — `--tpLevel` (multi-value, repeatable)** (issue #183, CLI power-user flag — no MCP / skill exposure). Enables true multi-tier take-profit on a single order, replacing the manual workaround of placing a second algo order after entry. Pass `--tpLevel` multiple times, each with a comma-separated `key:value` mini-DSL string (e.g. `--tpLevel "px:78000,sz:0.5,kind:limit" --tpLevel "px:81000,sz:0.5,kind:limit"`). Valid keys: `px` (tpOrdPx), `sz`, `kind` (tpOrdKind), `triggerPx` (tpTriggerPx), `triggerPxType`, `amendPxOnTrigger`, `clOrdId`. Applies to `okx {swap,spot,futures} place` and `okx {swap,spot,futures} algo place`. Conflict detection: passing both `--tpLevel` and `--tpTriggerPx`/`--tpOrdPx` raises a CLI-layer error. Backward compat: not passing `--tpLevel` produces identical wire payload to Phase 3a+c. MCP tool `inputSchema.properties` is unchanged — this flag is not discoverable via MCP tool descriptions or skill workflows, intentionally limiting autonomous agent use.
- **Phase 3a+c CLI power-user flags — `--tpTriggerRatio`, `--slTriggerRatio`, `--closeFraction`, `--tradeQuoteCcy`, `--banAmend`, `--pxAmendType`** (issue #182, CLI power-user flags — no MCP / skill exposure). Six new optional CLI flags for advanced quant users. `--tpTriggerRatio`/`--slTriggerRatio`: ratio-based TP/SL triggers (percentage from entry price) for algo place orders across swap/spot/futures. `--closeFraction`: partial-position close fraction for conditional/oco algo orders (mutually exclusive with `--sz`; OKX server enforces, returns 51000 on conflict — no CLI-side validation). `--tradeQuoteCcy`: select quote currency for SPOT place orders (e.g. USDT|USDC|BTC). `--banAmend`: disable OKX auto-amend on SPOT market orders. `--pxAmendType`: disable OKX auto-correction on out-of-range prices ("0"=allow auto-correct, "1"=reject). All flags are optional with no defaults; not passing them produces identical wire payload as Phase 2. MCP tool `inputSchema.properties` is unchanged — these flags are not discoverable via MCP tool descriptions or skill workflows, intentionally limiting autonomous agent use.
- **Phase 2 algo ordTypes — `trigger`, `chase`, `iceberg`, `twap`** (issue #181). Four new `ordType` values on `okx {swap,spot,futures} algo place`, closing the remaining OKX OpenAPI v5 enum gap. `trigger`: submit a pending order that activates when the market reaches `--triggerPx` (provide `--triggerPx` + `--orderPx`). `chase`: smart-follow best bid/ask within configurable distance/ratio bounds (`--chaseType`, `--chaseVal`, `--maxChaseType`, `--maxChaseVal`). `iceberg`: split a large order into child orders at fixed intervals (`--szLimit`, `--pxLimit`, `--timeInterval`, `--pxVar`/`--pxSpread`). `twap`: time-weighted average price split using the same parameter set as `iceberg`. Backward compat: existing `conditional`/`oco`/`move_order_stop` invocations produce identical wire payloads. Token budget delta: ~+600 tokens across 3 tools (4 new ordTypes × ~5 new fields each).
- **Phase 1 algo order flags — `--tpOrdKind`, `--tpTriggerPxType`, `--slTriggerPxType`, `--stpMode`, `--cxlOnClosePos`** (issue #178). Five new optional flags for trade order placement, closing the highest-ROI subset of the CLI/MCP↔OKX OpenAPI drift. `--tpOrdKind limit` places an immediate limit TP order (no trigger phase). `--tpTriggerPxType`/`--slTriggerPxType` control the TP/SL trigger price source (`last`/`index`/`mark`). `--stpMode` enables self-trade prevention (`cancel_maker`/`cancel_taker`/`cancel_both`). `--cxlOnClosePos` auto-cancels algo orders when the associated position closes. All flags are optional; not passing them yields identical wire payload as before. Applies to: `okx {swap,spot,futures,option} place`, `okx {swap,futures} algo place`, `okx spot algo place`.

### Fixed

- **`suggestSubcommand` no longer hallucinate non-existent subcommand paths** (issue #179). Previously, the `x-y → y x` heuristic in `packages/cli/src/unknown-command.ts` would suggest `"<b> <a>"` whenever `b` appeared in the module's `knownActions` list, without verifying that the combined path actually exists. For example, `okx swap set-leverage` suggested `okx swap leverage set`, which is not a registered subcommand. Fix: `suggestSubcommand` now accepts a `knownPaths: readonly string[]` parameter and only returns the suggestion when the combined path is explicitly listed. The legitimate `place-algo → algo place` positive case (#173) is preserved — callers pass `["algo place", "algo cancel", ...]` as `knownPaths`. Modules without multi-token subcommand paths default to `[]`, suppressing spurious suggestions entirely.
- **Codex CLI blocked from loading `okx-cex-trade` skill** — description field exceeded the 1024-char Codex limit (was 1448 chars). Trimmed by deduping synonymous trigger phrases; all concrete trade-type triggers preserved. Pre-emptively trimmed `okx-sentiment-tracker` (944 → 652 chars) and `okx-cex-market` (887 → 706 chars) for headroom. Added CI test `packages/cli/test/skill-description-length.test.ts` to enforce the 1024-char ceiling going forward.

## [1.3.2-beta.4] - 2026-04-24

### Added

- **OAuth Bearer token authentication (`okx auth`)**: New authentication method via the `okx-auth` Rust binary. Supports OAuth 2.1 device flow — `okx auth login` initiates browser-based login, `okx auth status` shows session state, `okx auth logout` revokes tokens. The binary handles token storage, refresh (300 s TTL lead), and scrypt + AES-256-GCM encryption. Tokens are read via fd3 pipe at request time with a 60 s JS-side cache. Auth mode is selected dynamically per request: API key HMAC (if configured) takes priority; OAuth Bearer token is used as fallback.
- **`okx auth install/install-status/remove` CLI commands**: Manage the `okx-auth` binary installation. CDN download with checksum verification, atomic replacement, and multi-source fallback — mirrors the DoH installer pattern.
- **`skills/okx-cex-auth/SKILL.md`**: New skill documentation for OAuth authentication workflows.
- **`postinstall` auto-download for okx-auth binary**: Best-effort download alongside the existing DoH binary during `npm install`.
- **`context-kg/` knowledge base**: Added `technical/06-oauth-authentication.md` covering OAuth subsystem architecture, binary distribution, fd3 token retrieval, auth priority, and CLI commands.

### Changed

- **`loadConfig()` is now async** (returns `Promise<OkxConfig>`): Startup now calls `execAuthStatus()` to detect OAuth login state.
- **`OkxConfig` requires `profile` field**: Resolved profile name is now included for OAuth token storage path resolution.
- **`OkxRestClient.buildHeaders()` is now async**: Supports dynamic auth method selection (API key HMAC or OAuth Bearer token) at request time.
- **`PLATFORM_MAP["linux-arm64"]` now maps to `linux-x64`** (`packages/core/src/pilot/installer.ts`). This matches the standard Docker Desktop test environment on Apple Silicon, where containers run under `linux/amd64` emulation. Native `linux-arm64` hosts will therefore install the `linux-x64` binary and rely on the host's binfmt / emulation layer. This is a deliberate alias, not a regression of the issue #166 fix — the entry is still present, just pointing at the x64 directory. A native `linux-arm64` CDN directory is tracked as future work.

### Fixed

- **`okx auth login` now refuses to start OAuth when API-key credentials are already configured.** Previously, `cmdAuthLogin` always spawned the `okx-auth` binary regardless of `~/.okx/config.toml` state. An agent following older guidance could start an OAuth device flow on a machine whose API-key profile was already good, producing a confusing login prompt and a URL/code the user did not need. `cmdAuthLogin` now calls `readFullConfig()` first: if any profile has a non-empty `api_key`, it prints `"API key already configured (profile: <name>). OAuth login skipped — API key will be used automatically."` and returns exit 0 without spawning the binary. In `--manual` mode the same outcome is encoded as JSON `{"status":"skipped","reason":"api_key_configured","profile":"<name>","message":"..."}` so agents can detect it programmatically. This belt-and-suspenders with the REST client's existing API-key preference (`rest-client.ts applyAuth` — API key is checked first and never falls back to OAuth).

- **`skills/okx-cex-auth/SKILL.md` pre-flight decision tree rewritten** to match the three-step flow: (1) check whether any `site` has been selected (union of `config show --json` profiles and `auth status --json`), and if not, present the site menu in chat verbatim before any login attempt; (2) check `api_key` — stop if present; (3) only then proceed to OAuth with the chosen `--site`. Previously the tree offered "First-Time Setup **or** Login Flow" as interchangeable paths for the "no credential" case, which let the model skip site selection and fall back to the OAuth binary's default (`global`). Also corrected the false claim that `okx config init` "handles site selection and OAuth login in one flow" — `cmdConfigInit` is an API-key wizard (site + demo/live + AK/SK/PP) and never performs OAuth. A new **Step 0.2.a** section was added for the invalid-API-key case: when an API-key profile exists but the API call returns `401 Unauthorized` / `Invalid Sign`, OAuth login is **not** a valid remediation (the REST client still prefers the broken API key; any OAuth token obtained afterwards would go unused). The agent must present exactly two neutral options — replace the API key, or remove the broken profile before starting OAuth — and let the user choose. This prevents the Haiku 4.5 failure mode observed in openclaw where the agent silently labelled OAuth as "recommended" even though OAuth could not have worked without first clearing the broken profile.

- **`skills/_shared/preflight.md` and `skills/okx-cex-portfolio/SKILL.md` auth-method detection corrected.** Both files previously used the `apiKey` field from `okx auth status --json` to branch between API-key and OAuth mode. That field reports the `okx-auth` binary's internal state and is **always** `false` regardless of whether `~/.okx/config.toml` contains an API-key profile; it cannot detect API-key users. Consequence: an agent following the old preflight would see `apiKey: false, status: not_logged_in`, conclude "no auth", and route the user into the OAuth login skill — even when a valid API-key profile already existed. Both files now require running **both** `okx config show --json` (authoritative for API-key presence) and `okx auth status --json` (authoritative for OAuth session state), with a decision table that checks API-key first and never relies on the unreliable `apiKey` status field.

- **`skills/okx-cex-trade/SKILL.md`, `skills/okx-cex-bot/SKILL.md`, `skills/okx-cex-earn/SKILL.md` Step A auth detection corrected.** Same class of bug as the preflight/portfolio fix above: the three skills' credential checks branched on `auth status --json` → `apiKey` (always `false`), so API-key users were misrouted into the OAuth login skill. Step A now runs both `okx config show --json` and `okx auth status --json`, checks API-key presence first, and only falls through to OAuth when no API-key profile is configured.

## [1.3.2-beta.3] - 2026-04-23

### Fixed

- **`event_get_orders` / `event_get_fills` returning empty arrays** — root cause: for EVENTS instType, `/api/v5/trade/fills` (3-day window) often returns empty while `/api/v5/trade/fills-history` (3-month) contains the data. The wrapper lacked `archive` mode and other query parameters. Added `archive` mode for fills, `status` (open/history/archive) routing for orders, time-range filters (`begin`/`end`), cursor pagination (`after`/`before`), and `ordId` filter. Also confirmed that `instFamily` is NOT supported for EVENTS on trade endpoints (causes HTTP 400). Response now includes `requestParams` for debugging.

### Changed

- **`smartmoney` description cleanup.** MCP / CLI / skill now consistently use "instId takes precedence if both set". Pool-filter descriptions keep enums / defaults / key semantics (`PNL_TOP20` = top 20 %, `period` = win-rate window only) but drop verbose prose; tool descriptions now state ts-or-dataVersion requirement up front. Docs only, no runtime change.

## [1.3.2-beta.2] - 2026-04-23

### Changed

- **`smartmoney signal` / `smartmoney_get_signal`: document `--instId` as recommended; `--instCcy` may return empty.** The `/api/v5/journal/smartmoney/signal` endpoint accepts `instCcy` per spec but in practice may return `data: []` even when the same `instCcy` works on `/overview`. Tool description, CLI reference, and API doc now steer callers to `--instId` (e.g. `BTC-USDT-SWAP`) for reliable single-currency signals. No code change — `instCcy` is still passed through.

- **`okx doh` command replaced by `okx pilot`** (issue #169). The `doh` CLI module is removed and replaced by `pilot` (`okx pilot status/install/remove`). Running `okx doh` will now report an unknown command.

- **CDN path unified: both `installer.ts` and `postinstall-notice.js` now use `/upgradeapp/tools/pilot`** (issue #169). Previously the two files were out of sync — `installer.ts` used `/upgradeapp/doh` while `postinstall-notice.js` was already at `/upgradeapp/tools/doh`. Both now converge on `/upgradeapp/tools/pilot`. The old paths are no longer valid.

#### BREAKING CHANGES

- **`OKX_DOH_BINARY_PATH` environment variable renamed to `OKX_PILOT_BINARY_PATH`**. No backward-compatible shim is provided. Update any scripts or shell profiles that set this variable.

- **`OKX_DOH_CACHE_PATH` environment variable renamed to `OKX_PILOT_CACHE_PATH`**. No backward-compatible shim is provided. Update any scripts or shell profiles that set this variable.

- **Cache file `~/.okx/doh-cache.json` replaced by `~/.okx/pilot-cache.json`**. The old file is now obsolete and can be safely deleted (`rm ~/.okx/doh-cache.json`). The new cache will be populated automatically on the next request.

- **`okx doh` command removed, replaced by `okx pilot`**. All three subcommands are available as `okx pilot status`, `okx pilot install`, `okx pilot remove`.

### Fixed

- **`okx market oi-history` table rendering fixed — no longer prints "No OI data" when data exists**. The API returns `data` as an array `[{ instId, bar, rows: [...] }]`, but the CLI was accessing `data["rows"]` directly on the array, which yielded `undefined` and always fell into the empty-data branch. The handler now unwraps `data[0]` before reading `rows`/`instId`/`bar`. `--json` mode was unaffected and keeps its current output. Unit tests updated to mirror the real array-wrapped API shape so this class of bug cannot recur silently.

- **`linux-arm64` platform now included in Pilot binary installer** (issue #166). `getPlatformDir()` was missing an entry for `"linux-arm64"`, causing install/update to fall back to `undefined` and write the binary to the wrong path on ARM64 Linux hosts. The entry `"linux-arm64": "linux-arm64"` is now present.

- **Pilot proxy re-resolution is now `await`-ed before continuing on network failure** (issue #166). Two call sites in `rest-client.ts` invoked `handleNetworkFailure()` as fire-and-forget (`handleNetworkFailure().catch(() => {})`), meaning the cache write and proxy state update could race with the retry request. Both sites now use `try { await this.pilot.handleNetworkFailure(); } catch {}`, ensuring the proxy node is fully resolved and the cache is persisted before the retry is issued.

- **`market` dispatcher: `orderbook`, `candles`, `trades`, `funding-rate` no longer emit spurious `Unknown market command` error and exit 1** (issue #175, regression introduced by commit `9fd4717` on 2026-04-14). The `handleMarketFilterCommand` refactor in that commit left an `errorLine + exitCode=1` block at its tail. Because `handleMarketPublicCommand` unconditionally tail-calls `handleMarketFilterCommand` as its fallback, the error fired before `handleMarketDataCommand` had a chance to dispatch the action — all four subcommands produced correct JSON on stdout but also wrote an error to stderr and exited 1, causing `set -e` scripts to hard-fail even though the underlying API call succeeded. Fix: removed the side-effect block from `handleMarketFilterCommand` (it now returns `undefined` silently on no match, consistent with every other sub-handler), and added `unknownSubcommand("market", action, [...])` in `handleMarketCommand` after both sub-dispatchers return `undefined` — the same pattern used by `swap`, `spot`, `futures`, `option`, `account`, and `bot` post-#173. Truly unknown market actions (e.g. `okx market foo`) continue to error with the structured diagnostic from `unknownSubcommand()` and exit 1.

- **`account_get_asset_balance` total asset valuation now defaults to USDT denomination** (issue #174). Previously, `showValuation=true` called `/api/v5/asset/asset-valuation` with no `ccy` parameter, causing OKX to default to BTC — a user with $3,834 in assets would see `0.049` instead of `3834`. A new `valuationCcy` parameter (default `"USDT"`) is now passed to the valuation endpoint. Callers can override to any OKX-supported currency (e.g. `valuationCcy="BTC"`). The chosen denomination is stamped as `valuationCcy` in the returned JSON. CLI: `okx account asset-balance --valuation` now shows USDT-denominated totals by default; use `--valuationCcy BTC` for BTC-denominated totals.

- **CLI no longer silently exits 0 on unknown subcommands** (issue #173). Previously, every second-level module dispatcher (`swap`, `spot`, `futures`, `option`, `account`, `bot`) fell through to `return undefined` when the action name didn't match any registered branch, producing an invisible failure — `okx swap place-algo` would exit 0 with no output, misleading scripts with `&& echo OK` and masking the real problem. Each dispatcher now calls the shared `unknownSubcommand()` helper which emits `Unknown command: okx <mod> <action>` to stderr, lists the available subcommands, suggests an MCP-name-to-CLI rewrite when applicable (`place-algo` → `algo place`), and sets a non-zero exit code. Reported via CS Telegram 2026-04-21 — customer's `okx --profile demo swap place-algo ...` returned silently, leaving them unable to tell whether the feature was broken or the command wrong.

- **`skills/okx-cex-trade/` reference docs now call out the CLI↔MCP naming mismatch.** `SKILL.md` has a top-level note; `references/swap-commands.md` has a dedicated "Naming — CLI vs MCP tool" table mapping each tool identifier to its CLI subcommand path. Motivated by the same #173 report: customers see `swap_place_algo_order` in MCP tool listings and guess the CLI form is `swap place-algo`, which silently failed pre-fix and now errors explicitly.

## [1.3.2-beta.1] - 2026-04-21

### Added

- **`spot_set_leverage` MCP tool and `okx spot leverage` CLI command**: Set the leverage ratio for a spot margin or cross-margin instrument. Accepts `--instId` (instrument-level) or `--ccy` (currency-level) alongside `--lever` and `--mgnMode`. Input is validated before the HTTP call — non-numeric, zero, or negative `lever` values are rejected immediately with an actionable error. Supports all 5 OKX leverage scenarios for SPOT/MARGIN.

- **Smart Money module** (`smartmoney`): 5 new read-only MCP tools (`smartmoney_get_overview`, `smartmoney_get_signal`, `smartmoney_get_signal_history`, `smartmoney_get_traders`, `smartmoney_get_trader_detail`) and corresponding CLI commands for accessing trader leaderboard, position analysis, and smart money signals.

- **`context-kg/` upstream API specs**: Three new business-domain reference docs under `context-kg/business/` capturing upstream OKX API contracts consumed by the repo — `06-leaderboard-smartmoney-api.md` (7 leaderboard / smart-money endpoints backing issue #94, with live-probe status and field-drift notes), `07-dcd-api.md` (8 DCD structured-product endpoints with state machine and error codes), `08-dca-api.md` (19 Spot/Contract DCA bot endpoints with sync-copy restrictions). Intended as the source of truth for cross-checking tool design, request/response shapes, and enum values during implementation.
- **`grid_amend_order` MCP tool and `okx bot grid amend` CLI command** — Amend a running grid bot without stopping it. Supports three modes combinable in a single call: price-range mode (`maxPx`+`minPx`+`gridNum`) to adjust the upper/lower boundary and grid count; TP/SL mode (`instId` + any of `tpTriggerPx`/`slTriggerPx`/`tpRatio`/`slRatio`) to set or clear take-profit/stop-loss; and combined mode for both at once. Pass `"-1"` to explicitly clear an existing TP or SL. CLI: `okx bot grid amend --algoId <id> [--maxPx ..] [--minPx ..] [--gridNum ..] [--instId ..] [--tpTriggerPx ..] [--slTriggerPx ..]`.

#### Breaking Changes

- **`grid_stop_order` MCP tool: `stopType` values `"3"`, `"5"`, and `"6"` explicitly removed** — These values are no longer valid for grid bot stop operations and must not be used. The valid set is now `["1","2"]` only: `"1"` closes all positions immediately (default clean exit), `"2"` stops the strategy without selling. Callers passing `"3"`, `"5"`, or `"6"` will fail schema validation. **Migration**: replace any usage of `"3"/"5"/"6"` with `"1"` (immediate close) or `"2"` (keep positions) based on the desired exit behaviour.

### Fixed

- **`swap_set_leverage` / `futures_set_leverage` input validation**: Invalid `lever` values (non-numeric, zero, negative) are now rejected before the HTTP call with a clear error message instead of surfacing an opaque OKX 51xxx error. `mgnMode` and `posSide` are validated against allowed enums. The `cross` + `long`/`short` combination is explicitly blocked with the hint "posSide only valid with isolated margin mode", matching OKX's business rule and reducing the ~9.7% failure rate from callers sending invalid combinations. Tool descriptions are rewritten to enumerate the three applicable SWAP/FUTURES scenarios (cross index-level / isolated one-way / isolated hedge) and explicitly flag portfolio-margin cross as unsupported.

### Changed

- Smart Money signal API paths changed: `/api/v5/journal/public/smartmoney/*` → `/api/v5/journal/smartmoney/*` to align with upstream OKX endpoint (4.1 signal, 4.2 signal-history, 4.3 overview).
- Removed demo-mode guard from Smart Money module — all 5 tools now work in both live and simulated trading mode. Previously they threw `ConfigError` in demo mode.

- **News CLI `--importance` default switched to `low`** for `okx news latest`, `okx news by-coin`, and `okx news search`. Previously these commands forwarded `undefined` to the server, which applies its `high`-only default and silently narrowed results. They now default to `low` (returns all news, both high and low importance) for broader browsing. Pass `--importance high` explicitly — or use the dedicated `okx news important` command — when you only want breaking / major news. MCP `news_get_latest` / `news_get_by_coin` / `news_search` tool descriptions updated to reflect the same semantics so AI agents pick `low` for broad queries and `high` only when the user explicitly asks for major news.

- **News skill: time-window handling for `--platform` queries**. The API's default `--begin` window is 72 hours, too narrow for bursty news sources and a frequent cause of empty results. `okx-sentiment-tracker` Source-Filtered News and Empty Results fallback sections now instruct agents to broaden `--begin` to 7 then 30 days before concluding a source has no data. The Known Limitations "Source Coverage" table that hardcoded per-platform activity labels was removed — those labels were based on the narrow 72-hour assumption and could mislead agents into giving up prematurely. Replaced with a generic rule that platform cadence is uneven and candidates should be resolved from `okx news platforms` rather than assumed.

---

## [1.3.1] - 2026-04-17

### Added

- **`news` module (restored)**: Orbit News API integration is back following compliance approval. Seven tools cover latest news, coin-specific news, search, article detail, platform listing, coin sentiment, and sentiment rankings. CLI: `okx news latest / by-coin / search / detail / platforms / sentiment / sentiment-ranking`. Supports `--platform` to filter by source (e.g. `blockbeats`, `odaily_flash`). `Accept-Language` uses standard IETF BCP 47 format. All news tools return a clear `ConfigError` in demo/simulated trading mode. (!251, !249, !235)

- **Event contract module** (`event`): New binary prediction-markets module with 9 MCP tools and matching CLI commands — browse open events, query contract details, place and manage event-contract orders. (!216)

- **Flash Earn module** (`earn.flash`): New instant-earn tools for flash-earn deposit and redemption operations. (!246)

- **Three new market tools** — `market_filter` (screen instruments by multi-dimensional criteria), `market_get_oi_history` (open interest history), and `market_get_oi_change_filter` (filter by OI change magnitude). CLI: `okx market filter / oi-history / oi-change-filter`. (!245)

- **Auto-generated CLI help from ToolSpec registry and `okx list-tools`**: CLI help is now derived from a declarative `CLI_REGISTRY` sourced from ToolSpec objects in `@agent-tradekit/core`, keeping help text in sync with the MCP tool registry. A new `okx list-tools [--json]` command serializes the full registry into structured JSON for AI agent self-discovery. (!234)

- **`okx doh` binary management commands**: `okx doh status` reports binary path, size, SHA-256, and CDN match; `okx doh install` downloads or updates the binary; `okx doh remove` deletes it (with confirmation or `--force`). DoH resolver status is also surfaced in `okx --version` and `okx diagnose`. (!232)

- **DoH (DNS-over-HTTPS) proxy for API requests**: When the OKX API domain is unreachable (e.g. DNS poisoning), the SDK transparently resolves an alternative proxy node via a local `okx-doh-resolver` binary, with cache-first strategy and automatic failed-node exclusion. `postinstall` downloads the platform binary to `~/.okx/bin/`; supports darwin-arm64, darwin-x64, linux-x64, linux-arm64, and win32-x64. (!230, !237)

- **`context-kg/` agent knowledge base with accuracy drift test**: Structured knowledge files for AI agents covering trading, market/account, earn/bot, errors, multi-site architecture, DoH proxy, `tgtCcy=margin` usage, and test quality rules. Automated drift test validates declared counts match actual code state at CI time. (#137, #160, !231, !238, !248)

### Fixed

- **Error code remediation hints now match OKX official API error reference**: Custom suggestions replaced by verbatim text from OKX's official API error documentation. (#163, !250)

- **CLI `list-tools` routing fix**: `okx list-tools` no longer falls through to "Unknown command" in the main router. (#161, !247)

- **CLI help text: missing parameters audited and restored**: All parameters identified as missing from CLI help output have been added back. (#155, !244)

- **`market_list_indicators`: improved descriptions and name validation**: Indicator names are now validated; unknown names return a clear error instead of silently returning empty results. (#153, !243)

- **`market_get_funding_rate` validates SWAP `instId`**: Non-SWAP instrument IDs are now rejected with a clear error before reaching the OKX API. (#152, !242)

- **Market filter docs: SPOT queries require explicit `quoteCcy=USDT`**: Clarified in tool and CLI descriptions that SPOT market queries must include `quoteCcy=USDT` to avoid empty results. (!257)

- **Skills language-neutral instructions**: Removed hardcoded Chinese-language prompts from `SKILL.md` so agent behavior is consistent regardless of session locale. (!233)

- **Skills: leverage error troubleshooting guidance**: Added specific remediation steps for leverage-related errors plus a general safeguard requiring read-only diagnosis before any write-operation fix. (!229)

- **CLI miscellaneous fixes**: Addressed cosmetic and behavioral issues flagged in code review. (#141, #142, #143, !236)

### Changed

- **Skills download: two-step presigned URL flow**: `skills_download` (MCP) and `okx skill download` (CLI) now obtain a short-lived presigned URL before fetching the skill archive, improving download security and reliability. (!240)

- **DoH resolver updated to v9**: Binary updated with revised protocol and CDN endpoint list. (!255)

- **Skills docs: TP/SL amend workflow clarified**: Skill documentation now guides users to `algo_amend_order` for modifying TP/SL on existing algo orders, improving discoverability. (!241)

- **CLI `okx news domains` renamed to `okx news platforms`**: Aligns CLI subcommand with the `--platform` parameter terminology.

- **Skill renamed `okx-cex-news` → `okx-sentiment-tracker`**: Skill directory and frontmatter name updated. MCP tool names (`news_*`) and CLI commands (`okx news`) are unchanged.

### Removed

- **`importance=medium` enum value**: Removed from `NEWS_IMPORTANCE` validation. The OKX API does not support `medium`; passing it returned a parameter error (51000). Only `high` and `low` are valid.

---

## [1.3.1-beta.7] - 2026-04-15

### Fixed

- **`okx list-tools` routing falls through to "Unknown command"**: Fixed command routing so `list-tools` is correctly dispatched without falling through to the default unknown-command handler. (#161)

---

## [1.3.1-beta.6] - 2026-04-14

### Added

- **Event Contract module**: New `event` module with 9 MCP tools and CLI commands for binary prediction markets — browse series/events/markets, place/amend/cancel orders, query orders/fills, and direction analysis with index price enrichment.
- **DoH (DNS-over-HTTPS) proxy for REST API requests**: Transparently resolves an alternative proxy node through a local `okx-pilot` binary when OKX API is unreachable via direct connection. Cache-first, zero overhead on cached paths. Supports `--verbose` logging.
- **Automatic DoH binary download on install**: `postinstall` downloads the platform-specific `okx-pilot` binary from CDN to `~/.okx/bin/`. Best-effort, never blocks `npm install`. Supports darwin-arm64, darwin-x64, linux-x64, linux-arm64, and win32-x64.
- **`okx doh` management commands**: `okx doh status`, `okx doh install`, `okx doh remove` for managing the DoH resolver binary. (#138)
- **DoH status in `okx --version` and `okx diagnose`**: Version output shows DoH resolver install status; `diagnose` checks binary existence and CDN checksum. (#138)
- **Auto-generated CLI help from ToolSpec registry**: CLI help text generated from declarative `CLI_REGISTRY` map, sourced from ToolSpec objects in `@agent-tradekit/core`. Bidirectional drift test catches mismatches at test time. (#140)
- **`okx list-tools [--json]` agent self-discovery command**: Serializes the full CLI registry into structured JSON for programmatic enumeration of all capabilities, parameters, and tool names. (#140)
- **TP/SL amend discoverability**: `{module}_amend_order` descriptions route users to `{module}_amend_algo_order` for modifying attached TP/SL. Skills `workflows.md` adds a "Modify existing TP/SL" scenario. (#151)
- **Market filter tools** (`market`): Three new MCP tools and CLI commands — `market_filter` / `okx market filter` (screen SPOT/SWAP/FUTURES by price, 24h change, market cap, volume, funding rate, OI with sort/limit support), `market_get_oi_history` / `okx market oi-history` (OI time-series with bar-over-bar delta), `market_filter_oi_change` / `okx market oi-change` (rank by OI change magnitude with filters).
- **`news` module restored**: 7 MCP tools and CLI commands for crypto news querying — `news_get_latest`, `news_get_by_coin`, `news_search`, `news_get_detail`, `news_get_domains`, `news_get_coin_sentiment`. Fixed `Accept-Language` header default.
- **Flash Earn module** (`earn.flash`): New `earn_get_flash_earn_projects` MCP tool and `okx earn flash-earn projects` CLI command for browsing upcoming and in-progress Flash Earn opportunities.
- **`context-kg/` knowledge base expanded**: Added DoH subsystem doc, `tgtCcy=margin` documentation, architecture updates, and full testing & QA specification. (#150)
- **Skills download two-step presign flow**: `skills_download` / `okx skill download` now uses a presigned URL flow for more reliable binary downloads.

### Changed

- **`market_get_indicator` improved descriptions and pre-call name validation**: Descriptions now list common indicator names and link to `market_list_indicators`. Unknown names return a `ValidationError` with similar-name suggestions before any API call. (#153)
- **`market_filter` `marketCapUsd` is SPOT-only**: Description clarified that `marketCapUsd` filter only applies to `instType=SPOT` per upstream API constraint.

### Fixed

- **Event Contract endpoints use authenticated requests**: All 4 event browse/query tools use `privateGet` — OKX's `/public/event-contract/*` endpoints require auth headers.
- **Skill docs: error-suggested remediation safeguard**: Agent must diagnose with read-only queries before acting on write-operation suggestions. MCP server returns `instructions` safeguard field. (#leverage)
- **CLI help missing params audit**: Added missing parameters in `spot`, `swap`, `futures` CLI help entries. (#155)
- **Skills: remove hardcoded Chinese prompts**: Replaced hardcoded Chinese disambiguation prompts in `SKILL.md` with language-adaptive English instructions.

---

## [1.3.1-beta.4] - 2026-04-10

### Added

- **DoH (DNS-over-HTTPS) proxy for REST API requests**: When the OKX API domain is unreachable via direct connection (e.g. DNS poisoning), the SDK now transparently resolves an alternative proxy node through a local `okx-pilot` binary. Cache-first strategy: first request attempts direct connection; on network failure the binary is invoked and the result is cached. Subsequent requests reuse the cached node with zero overhead. Failed proxy nodes are automatically excluded and re-resolved. Supports `--verbose` logging for full DoH lifecycle visibility.
- **Automatic DoH binary download on install**: `postinstall` now downloads the platform-specific `okx-pilot` binary from CDN (with multi-source fallback) to `~/.okx/bin/`. Best-effort — never blocks `npm install`. Supports darwin-arm64, darwin-x64, linux-x64, and win32-x64.
- **`context-kg/` knowledge base**: Bootstrap structured knowledge files for AI agents — 5 business domain docs (overview, trading, market/account, earn/bot, skills) + 4 technical docs (architecture, configuration, errors, multi-site) + quality placeholder. Includes `config.toml.example` `knowledge_dir` config entry. (#137)

### Fixed

- **Skill docs: error-suggested remediation safeguard** — Added a general safeguard rule: when an OKX API error suggests a fix involving write operations (cancel orders, close positions, stop bots), the agent must diagnose with read-only queries first and wait for user confirmation before acting. Also added specific leverage error troubleshooting guidance. Affected files: `swap-commands.md`, `futures-commands.md`, `workflows.md`, `SKILL.md`.
- **MCP server: remediation safeguard** — MCP server now returns `instructions` field with safeguard rule; error responses whose message suggests write-operation remediation (cancel/close/stop) are automatically annotated with a warning to diagnose first and confirm with the user.

---

## [1.3.1-beta.2] - 2026-04-09

### Added

- **Event Contract module**: New `event` module with 9 MCP tools and CLI commands for binary prediction markets — browse series/events/markets, place/amend/cancel orders, query orders/fills, and direction analysis with index price enrichment.

### Fixed

- **Event Contract endpoints use authenticated requests**: All 4 event browse/query tools (`event_browse_contracts`, `event_get_series`, `event_get_events`, `event_get_markets`) now use `privateGet` instead of `publicGet`. OKX's `/api/v5/public/event-contract/*` endpoints require auth headers despite the `/public/` path prefix; unauthenticated calls returned 401.

---

## [1.3.0] - 2026-04-08

### Added

- **`market_list_indicators` MCP tool and `okx market indicator list` CLI command**: Browse all supported OKX market indicators grouped by category, with range-filter support (`--fearGreedIndexMin/Max`, `--longShortRatioMin/Max`, etc.) for AI-driven sentiment screening. (#124)
- **Market tools `demo` parameter**: All market MCP tools now accept an optional `demo: boolean` parameter; CLI market commands respect the global `--demo` flag. Enables explicit querying of simulated-trading market data independently of the server's demo mode.
- **Simple Earn Fixed (定期赚币) tools** (`earn.savings`): Three new tools — `earn_get_fixed_order_list`, `earn_fixed_purchase` (two-step: preview then confirm), `earn_fixed_redeem`. `earn_get_lending_rate_history` now also returns fixed-term offers with APR, term, min amount, and remaining quota. CLI: `okx earn savings fixed-orders/fixed-purchase/fixed-redeem`.
- **Margin-cost order mode (`tgtCcy=margin`)**: SWAP, FUTURES, and options place/algo order tools now accept `tgtCcy=margin`, where `sz` represents the USDT margin cost. The system automatically queries current leverage and converts to contract count (`contracts = floor(margin × lever / (ctVal × lastPx))`). (#128)
- **CLI audit logging**: CLI writes audit logs to `~/.okx/logs/trade-YYYY-MM-DD.log` for all tool executions, matching MCP server behavior. `okx account audit-log` now works for CLI users. (#129)
- **`skills_download` `format` parameter**: Accepts `"zip"` or `"skill"`. MCP defaults to `"skill"` (agent-friendly extension), CLI defaults to `"zip"` (backward-compatible). File content is identical.

### Changed

- **CLI table output shows environment header**: Table output now displays an `Environment: live` / `Environment: demo (simulated trading)` header line.
- **`earn_get_lending_rate_history` fetches fixed-term offers**: Makes an additional best-effort `privateGet` call; falls back gracefully (empty `fixedOffers`) when no API key is configured.
- **`earn_get_lending_rate_history` default limit reduced from 100 to 7**: Reduces token usage in agent conversations.

### Fixed

- **Indicator range-filter code mapping**: Corrected internal code mappings and removed unsupported indicator types, preventing silent empty results.
- **Skills docs indicator sync**: Updated all indicator descriptions and examples to match live backend schema and new CLI commands.
- **Skills docs account transfer type codes**: Corrected `6`=funding / `18`=trading in portfolio and earn docs — previously reversed. (#126)
- **`tgtCcy=quote_ccy` conversion uses `minSz`/`lotSz`**: Rounds down to `lotSz` precision and validates against `minSz` instead of assuming integer contracts, fixing false "too small" errors for instruments with `minSz < 1` (e.g. BTC-USDT-SWAP). (#127)
- **CLI `--json` env wrapper is now opt-in via `--env` flag**: `--json` returns raw data by default (backward-compatible). Use `--json --env` for the `{env, profile, data}` wrapper. (#131)
- **Unknown `tgtCcy` values throw `ValidationError`**: Only `base_ccy`, `quote_ccy`, and `margin` are accepted; other values throw with a helpful suggestion instead of silently passing through. (#133)
- **`--verbose` flag now affects CLI audit log output**: Verbose mode writes a `debug`-level entry with full request args and response; non-verbose records a compact summary only. (#130)
- **Market data defaults to live regardless of server demo mode**: Market tools explicitly override the server-level demo flag, always returning live data unless `demo: true` is passed explicitly.

---

## [1.3.0-beta.5] - 2026-04-08

### Added

- **Skill download `format` parameter**: `skills_download` MCP tool and `okx skill download` CLI command now accept a `format` option (`"zip"` or `"skill"`). MCP defaults to `"skill"` (so agents like Claude Desktop can auto-detect the file type), CLI defaults to `"zip"` (backward-compatible). The file content is identical — only the extension changes.
- **Market tools `demo` parameter**: All 14 market MCP tools now accept an optional `demo: boolean` parameter, and CLI market commands now respect the global `--demo` flag. When `demo=true` / `--demo`, the request targets OKX's simulated trading market data environment (`x-simulated-trading: 1`). When omitted or `false` (default), live market data is always returned — independent of whether the server is started with `--demo`.

### Fixed

- **Market data defaults to live regardless of server demo mode**: Previously, starting the server with `--demo` caused all market data requests to return simulated trading data. Now market tools explicitly pass `simulatedTrading: false` by default, overriding the server-level demo flag. Users can pass `demo: true` to explicitly query simulated market data. Other modules (trading, account, earn, indicators) are unaffected and continue to follow the server demo flag.
- **Unknown `tgtCcy` values now throw `ValidationError` instead of silent passthrough**: Previously, typos like `--tgtCcy margin_ccy` or `--tgtCcy QUOTE_CCY` were silently ignored and `sz` was sent to the API unconverted. Now only `base_ccy`, `quote_ccy`, and `margin` are accepted; any other value throws a `ValidationError` with a helpful suggestion. (#133)
- **`--verbose` flag now affects CLI audit log output**: Previously, `TradeLogger` was always constructed with `"info"` level and all success logs used `"info"`, so `--verbose` had no effect on log file content. Now, verbose mode sets log level to `"debug"` and writes an additional debug-level entry with full request args and response data for each successful tool call, while non-verbose mode only records a compact summary. (#130)

---

## [1.3.0-beta.4] - 2026-04-08

### Added

- **DoH (DNS-over-HTTPS) proxy for REST API requests**: When the OKX API domain is unreachable via direct connection (e.g. DNS poisoning), the SDK now transparently resolves an alternative proxy node through a local `okx-pilot` binary. Cache-first strategy: first request attempts direct connection; on network failure the binary is invoked and the result is cached. Subsequent requests reuse the cached node with zero overhead. Failed proxy nodes are automatically excluded and re-resolved. Supports `--verbose` logging for full DoH lifecycle visibility.
- **Automatic DoH binary download on install**: `postinstall` now downloads the platform-specific `okx-pilot` binary from CDN (with multi-source fallback) to `~/.okx/bin/`. Best-effort — never blocks `npm install`. Supports darwin-arm64, darwin-x64, linux-x64, and win32-x64.

---

## [1.3.0-beta.2] - 2026-04-07

### Added

- **Simple Earn Fixed (定期赚币) tools** (`earn.savings`): Three new tools — `earn_get_fixed_order_list` (query fixed-term orders by ccy/state), `earn_fixed_purchase` (two-step purchase: preview with offer details then confirm; funds locked until maturity), `earn_fixed_redeem` (redeem a fixed-term order). `earn_get_lending_rate_history` now also returns available fixed-term offers with APR, term, min amount, and remaining quota. CLI: `okx earn savings fixed-orders`, `okx earn savings fixed-purchase`, `okx earn savings fixed-redeem`.
- **Margin-cost order mode (`tgtCcy=margin`)**: New `margin` value for `tgtCcy` parameter on SWAP, FUTURES, and options place/algo order tools. When `tgtCcy=margin`, `sz` represents the USDT margin cost; the system automatically queries the current leverage and converts to the correct number of contracts (formula: `contracts = floor(margin * lever / (ctVal * lastPx))`). Existing `quote_ccy` (notional value) and `base_ccy` (contracts) modes are unchanged. Skills confirmation templates now require explicit disambiguation when a user says "500U" — is it notional value or margin cost? (#128)
- **CLI audit logging**: CLI now writes audit logs to `~/.okx/logs/trade-YYYY-MM-DD.log` for all tool executions, matching MCP server behavior. `okx account audit-log` now works for CLI users. (#129)

### Changed

- **`earn_get_lending_rate_history` now fetches fixed-term offers via authenticated API** (`earn.savings`): This tool now makes an additional `privateGet` call to retrieve fixed-term product offers. The call is best-effort — if the user has no API key configured, the tool still returns flexible lending rate history as before, with an empty `fixedOffers` array.
- **`earn_get_lending_rate_history` default limit reduced from 100 to 7** (`earn.savings`): When `limit` is omitted, the tool now returns the 7 most recent records instead of 100, reducing token usage in agent conversations.

### Fixed

- **CLI `--json` env wrapper is now opt-in via `--env` flag**: Reverts the breaking change from 1.3.0-beta.1 where `--json` output was wrapped in `{env, profile, data}`. Now `--json` returns raw data by default (backward compatible). Use `--json --env` to get the wrapper with environment metadata. Table output environment header is unaffected. (#131)
- **`tgtCcy=quote_ccy` conversion: use `minSz`/`lotSz` instead of `Math.floor`**: The USDT-to-contract conversion now rounds down to `lotSz` precision and compares against `minSz` from the instruments API, instead of assuming integer contracts. Fixes false "too small" errors for instruments where `minSz < 1` (e.g. BTC-USDT-SWAP with `minSz=0.01`). (#127)

---

## [1.3.0-beta.1] - 2026-04-07

### Added

- **`market_list_indicators` MCP tool and `okx market indicator list` CLI command**: List OKX market indicators with filtering by category, page, and limit. Supports range-filter flags (`--fearGreedIndexMin/Max`, `--longShortRatioMin/Max`, etc.) for AI-driven market sentiment screening. (#124)

### Fixed

- **Indicator range-filter code mapping**: Corrected internal code mappings for range-filter parameters and removed indicator types unsupported by the OKX API, preventing silent empty results.
- **Skills docs indicator sync**: Updated all indicator-related descriptions and example outputs in skills docs to match the live backend data schema and new CLI commands.
- **Skills docs account transfer type codes swapped**: Corrected `6`=funding / `18`=trading in portfolio and earn skills documentation — previously written in reverse. (#126)

### Changed

- **CLI `--json` output now includes environment metadata**: `--json` output changed from raw OKX API response to `{"env", "profile", "data"}` wrapper. Scripts using `jq '.[0].field'` must update to `jq '.data[0].field'`. Table output now displays an environment header line (`Environment: live` / `Environment: demo (simulated trading)`). (#207, closes #117)

---

## [1.2.9] - 2026-04-06

### Added

- **Skills Marketplace third-party disclaimer**: Added notices at key trust-decision points (marketplace prompt, install/download descriptions, and CLI install flow) to make clear that listed skills are created by independent third-party developers before installation.

### Fixed

- **SWAP/FUTURES/options `tgtCcy=quote_ccy` auto-conversion**: Order handlers now automatically convert quote-currency amounts (for example, USDT) into contract counts before sending SWAP, FUTURES, and options orders/algo orders to the OKX API, preventing oversized positions caused by treating quote amounts as raw contract size. (#114)
- **`dcd_subscribe` yield threshold comparison**: `annualizedYield` is now converted from decimal to percent before comparing against `minAnnualizedYield`, so threshold filtering works correctly and invalid yield values are rejected.
- **Skills docs `tgtCcy` wording**: Clarified that `tgtCcy` is handled by an internal conversion layer rather than passed through directly to the OKX API, reducing sizing confusion in skills documentation.
- **CLI docs: negative values must use `=` form**: Updated all skill references (swap/futures/spot command docs, workflows, SKILL.md) to use `--tpOrdPx=-1` / `--slOrdPx=-1` instead of the space form, which Node `parseArgs()` misinterprets as a flag. Added notes to parameter tables clarifying this requirement. (#123, closes #115)

---

## [1.2.9-beta.2] - 2026-04-06

### Added

- **Skills Marketplace third-party disclaimer**: Added notices at key trust-decision points (SKILL.md agent prompt, `skills_download` tool description, CLI install output, and module docs) to inform users that skills are created by independent third-party developers before installation.

### Fixed

- **SWAP/FUTURES/options `tgtCcy=quote_ccy` auto-conversion**: when `tgtCcy=quote_ccy` is set on SWAP, FUTURES, or options algo orders, the handler now automatically converts the USDT amount to contract count before sending to the OKX API — preventing silent position amplification where e.g. "100 USDT" became "100 contracts (~$6,700)". Conversion fetches `ctVal` and `lastPx` in parallel and logs a `_conversion` note in the response. (#114)
- **`dcd_subscribe` yield threshold comparison**: OKX API returns `annualizedYield` as a decimal fraction (e.g. `0.18` = 18%), but `minAnnualizedYield` was compared directly against the raw value, causing all yield threshold checks to fail. Now correctly multiplies by 100 before comparison. Also rejects with `INVALID_YIELD_VALUE` when the quote returns a non-numeric yield.
- **DCD tool descriptions**: Added yield unit clarification (`annualizedYield` is decimal, not percent) to `dcd_get_products`, `dcd_get_orders`, and `dcd_subscribe` descriptions to prevent LLM misinterpretation.

---

## [1.2.8] - 2026-04-03

### Added

- **`market_get_instruments_by_category` MCP tool and `okx market instruments-by-category` CLI command**: Discover tradeable instruments by `instCategory` — Stock tokens (3), Metals (4), Commodities (5), Forex (6), Bonds (7). Supersedes `market_get_stock_tokens` for category 3. (#109)
- **Skills Marketplace module** (`skills`): Browse, search, and install AI trading skills. Tools: `skills_get_categories`, `skills_search`, `skills_download`. CLI: `okx skill search/categories/add/download/remove/check/list`. Enabled by default.
- **`--live` flag**: Forces live trading mode even when the active profile has `demo=true`. Mutually exclusive with `--demo`. (#108)
- **Three-channel auto-update** (`okx upgrade`): Supports stable, beta, and latest dist-tag channels with automatic skill version sync after upgrade.
- **`account_get_asset_balance` `showValuation` parameter**: Returns total asset valuation breakdown across all account types (trading, funding, earn, etc.). CLI: `okx account asset-balance --valuation`. (#102)
- **`market_get_candles` historical endpoint auto-routing**: Automatically routes to `/market/history-candles` when `after`/`before` timestamps are older than 2 days. The `history` parameter has been removed; no manual switching required. (#101)
- **`okx-cex-trade` SKILL.md restructured with reference files**: Extracted detailed CLI param tables into `references/spot-commands.md`, `references/swap-commands.md`, `references/futures-commands.md`, `references/options-commands.md`, `references/workflows.md`, `references/templates.md` for lighter agent loading.

### Fixed

- **Contract order placement requires `ctVal` lookup**: `swap_place_order`, `futures_place_order`, and `option_place_order` now mandate calling `market_get_instruments` first to retrieve `ctVal` (contract face value) before placing orders. (#113)
- **`account_get_config` `settleCcy`/`settleCcyList`**: These USDS-contract-only fields are now preserved in the response with added description to avoid AI model misinterpretation.
- **Earn write tools blocked in demo mode**: All earn write operations now return a clear `ConfigError` in simulated trading mode instead of an opaque 500 error from OKX API.
- **`account_get_asset_balance` zero balance display**: Correctly shows `0` instead of "(no data)" when account balance is exactly 0.
- **`--no-demo` flag correctly overrides profile `demo=true`**: Three-state resolution: `--live` forces live, `--demo` forces demo, otherwise profile is consulted. (#108)
- **`okx upgrade` security fixes**: Resolves `npm` via `process.execPath` (S4036), eliminates ReDoS hotspot (S5852), replaces `execSync` with `spawnSync` (S4721).
- **Preflight drift check skipped for prerelease CLI**: Avoids false-positive warnings when local CLI version contains a prerelease suffix.

### Deprecated

- **`market_get_stock_tokens`**: Replaced by `market_get_instruments_by_category` with `instCategory="3"`. Retained for backward compatibility; will be removed in a future major version.
- **`okx market stock-tokens`**: Replaced by `okx market instruments-by-category --instCategory 3`. Retained for backward compatibility; will be removed in a future major version.

### Removed

- **`news` module**: Orbit News API integration removed pending regulatory compliance approval. Will be re-introduced once approval is obtained.

---

## [1.2.8-beta.7] - 2026-04-03

### Removed

- **`news` module removed pending compliance approval**: The Orbit News API integration introduced in [1.2.8-beta.4] has been reverted. All news tools (`news_get_latest`, `news_get_by_coin`, `news_search`, `news_get_detail`, `news_get_domains`, `news_get_coin_sentiment`, `news_get_sentiment_ranking`), CLI commands (`okx news …`), and the `okx-sentiment-tracker` agent skill have been removed until regulatory compliance approval is obtained. The `skills` (Skill Marketplace) module is unaffected.

---

## [1.2.8-beta.6] - 2026-04-02

### Fixed

- **Contract order placement now requires `ctVal` lookup first**: `swap_place_order`, `futures_place_order`, and `option_place_order` tool descriptions now include a mandatory precondition to call `market_get_instruments` to retrieve `ctVal` (contract face value) before placing orders. The `sz` parameter description is also clarified with an example (e.g. ETH-USDT-SWAP: 1 contract = 0.1 ETH). `okx-cex-trade` SKILL.md updated with a critical warning section. (#113)
- **`account_get_config`: revert field stripping, add description instead**: The beta.5 fix that stripped `settleCcy`/`settleCcyList` from the response has been reverted. These fields are now preserved and explained in the tool description — they only apply to USDS-margined contracts and can be ignored for standard USDT/coin-margined trading.

---

## [1.2.8-beta.5] - 2026-04-02

### Added

- **`market_get_instruments_by_category` MCP tool and `okx market instruments-by-category` CLI command**: Discover tradeable instruments by `instCategory` — Stock tokens (3, e.g. AAPL-USDT-SWAP), Metals (4, e.g. XAUUSDT-USDT-SWAP), Commodities (5, e.g. OIL-USDT-SWAP), Forex (6, e.g. EURUSDT-USDT-SWAP), Bonds (7, e.g. US30Y-USDT-SWAP). Accepts `--instCategory <3|4|5|6|7>`, optional `--instType` (default SWAP) and `--instId`. Supersedes `market_get_stock_tokens` / `okx market stock-tokens` for category 3. (#109)
- **`okx-cex-market` skill updated**: Description, command index, instrument-commands reference, and workflows updated to cover all non-crypto asset categories. New "Non-crypto asset discovery" workflow guides agents from instrument discovery → price check → order sizing. (#109)
- **Skills Marketplace module** (`skills`): Browse, search, and install AI trading skills from the OKX Skills Marketplace. Enabled by default. Activate with `--modules skills`.
  - `skills_get_categories` — List all available skill categories; use `categoryId` as input to `skills_search`.
  - `skills_search` — Search skills by keyword and/or category; returns `totalPage` for pagination.
  - `skills_download` — Download a skill zip to a local directory.
  - CLI: `okx skill search <keyword>`, `okx skill categories`, `okx skill add <name>`, `okx skill download <name> [--dir]`, `okx skill remove <name>`, `okx skill check <name>`, `okx skill list`.
  - `okx skill add` automatically extracts, validates `SKILL.md`, runs `npx skills add`, and records the install in `~/.okx/skills/registry.json`.
  - Agent Skill: `skills/okx-cex-skill-mp/SKILL.md`.

### Deprecated
- **`market_get_stock_tokens` MCP tool**: Replaced by `market_get_instruments_by_category` with `instCategory="3"`. Retained for backward compatibility; will be removed in a future major version.
- **`okx market stock-tokens` CLI command**: Replaced by `okx market instruments-by-category --instCategory 3`. Retained for backward compatibility; will be removed in a future major version.

### Fixed

- **Earn module: write operations now return a clear error in simulated trading (demo) mode** instead of hitting OKX API and receiving an opaque 500 server error. A unified `withDemoGuard` wrapper in `earn/index.ts` intercepts all earn write tools (savings purchase/redeem, DCD subscribe, on-chain staking, auto-earn) before execution and throws a `ConfigError` with the message: "Earn features (savings, DCD, on-chain staking, auto-earn) are not available in simulated trading mode." — with suggestion to switch to a live account. Read-only tools (balance queries, rate history, offer listings) remain accessible in demo mode. `dcd_redeem` preview mode (no `quoteId`, read-only price check) is also permitted. New earn tools added in the future are automatically protected based on their `isWrite` flag.
- **`account_get_config` response strips `settleCcy` / `settleCcyList`**: These USDS-contract-only fields are now removed from the response to avoid confusing AI models that interpret them as general account settings. *(Reverted in [1.2.8-beta.6] — fields are preserved with added description instead.)*

---

## [1.2.8-beta.4] - 2026-04-02

### Added

- **`news` module** (7 tools): Real-time crypto news, full-text search, and sentiment analytics via Orbit News API. All tools are read-only and require no fund permissions. Activate with `--modules news`.
  - `news_get_latest` — Latest news sorted by time; supports importance filter (`high`/`medium`/`low`), coin filter, language, pagination.
  - `news_get_by_coin` — News for specific coins (comma-separated, e.g. `BTC,ETH`).
  - `news_search` — Full-text keyword search with optional coin, importance, sentiment, and sort filters.
  - `news_get_detail` — Full article content (title + AI summary + original text) by news ID.
  - `news_get_domains` — List available news source domains (e.g. CoinDesk, CoinTelegraph).
  - `news_get_coin_sentiment` — Bullish/bearish snapshot or time-series trend for coins; pass `trendPoints` for trend mode.
  - `news_get_sentiment_ranking` — Rank coins by hotness or sentiment direction.
  - CLI: `okx news latest`, `okx news by-coin <coins>`, `okx news search <keyword>`, `okx news detail <id>`, `okx news domains`, `okx news sentiment <coins>`, `okx news sentiment-ranking`.
  - Agent Skill: `skills/okx-sentiment-tracker/` with workflows guide.

### Added

- **`--live` flag for CLI and MCP server**: Forces live trading mode even when the active profile has `demo=true`. Mutually exclusive with `--demo` (passing both throws an error). CLI: `okx --live <module> <action>`. MCP: `--live` argument. (#108)

### Fixed
- **`--no-demo` flag now correctly overrides profile `demo=true`**: Previously, `cli.demo` was treated as always-truthy when the default was `false`, so `--no-demo` had no effect against a profile with `demo=true`. The resolution logic now uses a three-state check: `--live` forces live, `--demo` forces demo, otherwise env vars and profile are consulted. (#108)

---

## [1.2.8-beta.3] - 2026-04-01

### Added

- **Three-channel auto-update with skill version sync** (`okx upgrade`): Supports stable, beta, and latest dist-tag channels. Automatically syncs bundled agent-skills version after upgrade. Exports `fetchLatestVersion`, `isNewerVersion`, `fetchDistTags` from core for version resolution.
- **`okx-cex-trade` SKILL.md restructured with separate reference files**: Reduced the monolithic 1,594-line `SKILL.md` to a lean 342-line index by extracting CLI param tables and workflows into `references/spot-commands.md`, `references/swap-commands.md`, `references/futures-commands.md`, `references/options-commands.md`, `references/workflows.md`, and `references/templates.md`. Follows the same pattern as `okx-cex-earn` and `okx-cex-market`. Agents can dynamically load only the reference sections they need.

### Fixed

- **`okx upgrade`: resolve `npm` via `process.execPath`** instead of relying on `PATH` lookup, fixing upgrade failures in environments where `npm` is not on PATH (SonarQube S4036).
- **`okx upgrade`: eliminate ReDoS hotspot** — replaced regex-based string replace with `split`/`join` (SonarQube S5852).
- **`okx upgrade`: replace `execSync` with `spawnSync`** to silence security hotspot (SonarQube S4721).
- **Preflight drift check skipped for prerelease CLI**: When the local CLI version contains a prerelease suffix (e.g. `1.2.8-beta.3`), the version drift check is now skipped to avoid false-positive warnings.

---

## [1.2.8-beta.2] - 2026-03-31

### Fixed

- **`account_get_asset_balance` shows zero balance instead of "(no data)"**: When an account balance is exactly 0, the CLI now correctly displays `0` rather than the placeholder "(no data)" text.

### Changed

- **`market_get_candles` now automatically routes to historical endpoint**: Automatically uses `/market/history-candles` when `after`/`before` timestamps are older than 2 days, enabling access to candlestick data back to 2021. Includes fallback: if the recent endpoint returns empty data for a timestamped request, it retries the history endpoint. The `history` parameter has been removed; no manual switching required. CLI: `okx market candles BTC-USDT --after <timestamp>`. (#101)
- **`account_get_asset_balance` now supports `showValuation` parameter**: Set `showValuation=true` to also return total asset valuation breakdown across all account types (trading, funding, earn, etc.) via `/api/v5/asset/asset-valuation`. Default behavior is unchanged (backward compatible). CLI: `okx account asset-balance --valuation`. (#102)

---

## [1.2.8-beta.1] - 2026-03-31

### Added

- **DoH (DNS-over-HTTPS) node resolution infrastructure** *(experimental — code was subsequently removed from the codebase via merge conflict and is not included in the stable 1.2.8 release)*: Introduced `packages/core/src/doh/` with `DohNode` type and `resolveDoh()` resolver. The REST client integrated DoH-based proxy node selection for improved connectivity in restricted network environments. Removed pending platform-specific native binary integration (`@okx_ai/doh-darwin`, `doh-linux`, `doh-win32`).

---

## [1.2.7] - 2026-03-27

### Added

- **`earn_auto_set` tool** (`earn.autoearn`): Enable or disable auto-earn for a currency. Supports `earnType='0'` for auto-lend+stake (most currencies) and `earnType='1'` for USDG earn (USDG, BUIDL). Cannot disable within 24 hours of enabling. CLI: `okx earn auto on <ccy>` / `okx earn auto off <ccy>`.
- **Contract grid supports coin-margined (inverse) instruments** (e.g. `BTC-USD-SWAP`): Updated `grid_create_order`, `grid_get_orders`, and `grid_stop_order` tool descriptions to document CoinM support, including coin-margined instId examples and margin unit clarification.
- **`grid_create_order` TP/SL params**: Added `tpTriggerPx`, `slTriggerPx` (trigger price) and `tpRatio`, `slRatio` (ratio-based, contract only) so users can set take-profit and stop-loss when creating a grid bot.
- **`grid_create_order` `algoClOrdId`**: User-defined algo order ID (alphanumeric, max 32 chars). Unique per user — enables idempotent creation and can be used to query or stop the bot later.
- **`tgtCcy` parameter for algo place orders**: `spot_place_algo_order`, `swap_place_algo_order`, `futures_place_algo_order`, and `option_place_algo_order` now accept `tgtCcy`. Set `tgtCcy=quote_ccy` to specify order size in USDT instead of contracts/base currency. (#86)
- **`okx diagnose --mcp` multi-client detection**: Detects Cursor, Windsurf, Claude Code, and Claude Desktop configs; skips missing clients instead of failing; passes when at least one client is configured. (#90)
- **`okx diagnose --mcp` tool count limit check**: Warns when total tool count exceeds known client limits (e.g. Cursor: 40/server, 80 total) and suggests `--modules` to reduce. (#90)
- **Cursor tool limit guidance**: Added warning, recommended module combinations table, and safe configuration examples to `docs/configuration.md` and `docs/faq.md` for Cursor users affected by the ~40 tools/server limit. (#88)
- **Spot DCA support** (`bot.dca`): All 5 DCA tools now support both Spot DCA (`algoOrdType=spot_dca`) and Contract DCA (`algoOrdType=contract_dca`). New parameters: `algoOrdType` (required), `algoClOrdId`, `reserveFunds`, `tradeQuoteCcy` for `dca_create_order`; `algoOrdType` and `stopType` for `dca_stop_order`; `algoOrdType` filter for `dca_get_orders`; `algoOrdType` required for `dca_get_order_details` and `dca_get_sub_orders`. CLI commands updated with matching `--algoOrdType` option (defaults to `contract_dca` for backward compatibility).
- **`dca_create_order` RSI trigger support**: `triggerStrategy` now accepts `"rsi"` for both spot and contract DCA. New RSI parameters: `triggerCond` (`cross_up` | `cross_down`), `thold` (RSI threshold, e.g. `"30"`), `timeframe` (e.g. `"15m"`), `timePeriod` (default `"14"`). Note: `price` trigger is only supported for `contract_dca`; `spot_dca` supports `instant` and `rsi` only.
- **Agent Skills bundled in `skills/`**: All 5 skill modules (`okx-cex-market`, `okx-cex-trade`, `okx-cex-portfolio`, `okx-cex-bot`, `okx-cex-earn`) are now included directly in the repository under `skills/`. Includes `skills/README.md` and `skills/README.zh-CN.md` with usage guide.

### Fixed

- **`dca_create_order` missing `tag` field**: The `tag` field (from `context.config.sourceTag`) is now correctly included in the create request body, matching `grid_create_order` behavior.
- **`allowReinvest` type mismatch**: Schema changed from string enum to boolean to match the backend `Boolean` type. Handler accepts both boolean and string "true"/"false" for CLI compatibility.
- **`cmdDcaSubOrders` wrong table columns**: When querying orders within a cycle (with `--cycleId`), the CLI now displays order-specific fields (`ordId`, `side`, `ordType`, `filledSz`, etc.) instead of cycle-list fields.
- **`okx market ticker` showed wrong "24h change %" field**: The field was incorrectly mapped to `sodUtc8` (UTC+8 daily open price) instead of being calculated from `open24h`. Now correctly displays `24h open` (the `open24h` value) and a computed `24h change %` (derived from `open24h` and `last`).
- **`dca_create_order` `triggerStrategy` validation by `algoOrdType`**: `price` trigger is rejected for `spot_dca` at validation time with a clear error message.

### Changed

- **`grid_create_order`: `direction` is now required for contract grids** — MCP-side validation rejects requests missing `direction` when `algoOrdType=contract_grid`, providing immediate client-side feedback without a network round-trip.
- **`grid_stop_order`: default `stopType` changed from `"2"` to `"1"`** — omitting `stopType` now defaults to close-all (stop grid and close positions) instead of keep-assets, which is the safer and more intuitive default for both spot and contract grids.
- **`grid_create_order`: shortened tool descriptions** — reduced `grid_create_order` JSON schema size by ~20% (2,017 → 1,610 chars) by tightening parameter descriptions without removing any information.
- **README updated with Agent Skills section**: Features table and Documentation table updated to reflect the bundled `skills/` directory.

---

## [1.2.7-beta.3] - 2026-03-27

### Added

- **`dca_create_order` RSI trigger support**: `triggerStrategy` now accepts `"rsi"` for both spot and contract DCA. New RSI parameters: `triggerCond` (`cross_up` | `cross_down`), `thold` (RSI threshold, e.g. `"30"`), `timeframe` (e.g. `"15m"`), `timePeriod` (default `"14"`). RSI trigger is supported by both `spot_dca` and `contract_dca`.
- **Agent Skills bundled in `skills/`**: All 5 skill modules (`okx-cex-market`, `okx-cex-trade`, `okx-cex-portfolio`, `okx-cex-bot`, `okx-cex-earn`) are now included directly in the repository under `skills/`. Includes `skills/README.md` and `skills/README.zh-CN.md` with usage guide.

### Fixed

- **`dca_create_order` `triggerStrategy` validation by `algoOrdType`**: `price` trigger is now rejected for `spot_dca` at validation time with a clear error message (`spot_dca` supports `instant` and `rsi` only). `contract_dca` continues to support all three strategies (`instant`, `price`, `rsi`).

### Changed

- **README updated with Agent Skills section**: Features table and Documentation table updated to reflect the bundled `skills/` directory.

---

## [1.2.7-beta.2] - 2026-03-27

### Added

- **`okx diagnose --mcp` multi-client detection**: detects Cursor, Windsurf, Claude Code, and Claude Desktop configs; skips missing clients instead of failing; passes when at least one client is configured (#90)
- **`okx diagnose --mcp` tool count limit check**: warns when total tool count exceeds known client limits (e.g. Cursor: 40/server, 80 total) and suggests `--modules` to reduce (#90)
- **Cursor tool limit guidance**: added warning, recommended module combinations table, and safe configuration examples to `docs/configuration.md` and `docs/faq.md` for Cursor users affected by the ~40 tools/server limit (#88)
- **Spot DCA support** (`bot.dca`): All 5 DCA tools now support both Spot DCA (`algoOrdType=spot_dca`) and Contract DCA (`algoOrdType=contract_dca`). New parameters: `algoOrdType` (required), `algoClOrdId`, `reserveFunds`, `tradeQuoteCcy` for `dca_create_order`; `algoOrdType` and `stopType` for `dca_stop_order`; `algoOrdType` filter for `dca_get_orders`; `algoOrdType` required for `dca_get_order_details` and `dca_get_sub_orders`. CLI commands updated with matching `--algoOrdType` option (defaults to `contract_dca` for backward compatibility). Help text and agent-skills documentation updated.

### Removed

- **`dca_create_order` `triggerStrategy` no longer supports `"rsi"`**: OKX DCA API does not support RSI trigger for DCA bots. The `triggerStrategy` enum is now `["instant", "price"]`. Users previously passing `triggerStrategy: "rsi"` will receive a schema validation error.

### Fixed

- **`dca_create_order` missing `tag` field**: The `tag` field (from `context.config.sourceTag`) is now correctly included in the create request body, matching `grid_create_order` behavior.
- **`allowReinvest` type mismatch**: Schema changed from string enum to boolean to match the backend `Boolean` type. Handler accepts both boolean and string "true"/"false" for CLI compatibility.
- **`cmdDcaSubOrders` wrong table columns**: When querying orders within a cycle (with `--cycleId`), the CLI now displays order-specific fields (`ordId`, `side`, `ordType`, `filledSz`, etc.) instead of cycle-list fields.
- **`okx market ticker` showed wrong "24h change %" field**: The field was incorrectly mapped to `sodUtc8` (UTC+8 daily open price) instead of being calculated from `open24h`. Now correctly displays `24h open` (the `open24h` value) and a computed `24h change %` (derived from `open24h` and `last`).

---

## [1.2.7-beta.1] - 2026-03-26

### Added

- **`earn_auto_set` tool** (`earn.autoearn`): Enable or disable auto-earn for a currency. Supports `earnType='0'` for auto-lend+stake (most currencies) and `earnType='1'` for USDG earn (USDG, BUIDL). Cannot disable within 24 hours of enabling. CLI: `okx earn auto on <ccy>` / `okx earn auto off <ccy>`.
- **Contract grid now supports coin-margined (inverse) instruments** (e.g. `BTC-USD-SWAP`): Updated `grid_create_order`, `grid_get_orders`, and `grid_stop_order` tool descriptions to document CoinM support, including coin-margined instId examples and margin unit clarification.
- **`grid_create_order` now supports TP/SL params**: Added `tpTriggerPx`, `slTriggerPx` (trigger price) and `tpRatio`, `slRatio` (ratio-based, contract only) so users can set take-profit and stop-loss when creating a grid bot.
- **`grid_create_order` now supports `algoClOrdId`**: User-defined algo order ID (alphanumeric, max 32 chars). Unique per user — enables idempotent creation and can be used to query or stop the bot later.
- **`tgtCcy` parameter for algo place orders**: `spot_place_algo_order`, `swap_place_algo_order`, `futures_place_algo_order`, and `option_place_algo_order` now accept `tgtCcy`. Set `tgtCcy=quote_ccy` to specify order size in USDT instead of contracts/base currency, consistent with regular place order tools added in v1.2.6. (#86)

### Changed

- **`grid_create_order`: `direction` is now required for contract grids** — MCP-side validation rejects requests missing `direction` when `algoOrdType=contract_grid`, providing immediate client-side feedback without a network round-trip.
- **`grid_stop_order`: default `stopType` changed from `"2"` to `"1"`** — omitting `stopType` now defaults to close-all (stop grid and close positions) instead of keep-assets, which is the safer and more intuitive default for both spot and contract grids.
- **`grid_create_order`: shortened tool descriptions** — reduced `grid_create_order` JSON schema size by ~20% (2,017 → 1,610 chars) by tightening parameter descriptions (`sz`, `algoClOrdId`, TP/SL fields) without removing any information.
---

## [1.2.6] - 2026-03-23

### Added

- **`market_get_indicator` tool** (`market`): Query technical indicator values for any instrument via the OKX AIGC indicator API. Supports 70+ indicators across 10 categories — moving averages (MA, EMA, WMA, HMA…), trend (MACD, SuperTrend, SAR, ADX…), Ichimoku, momentum oscillators (RSI, KDJ, StochRSI…), volatility (BB, ATR, Keltner…), volume (OBV, VWAP, MFI…), statistics (LR, Slope, Sigma…), price auxiliary (TP, MP), candlestick patterns (15 types), and BTC crypto-cycle indicators (BTCRAINBOW, AHR999). No API credentials required. Accepts optional `params`, `returnList`, `limit`, and `backtestTime`. CLI: `okx market indicator <name> <instId> [--bar <tf>] [--params <p1,p2>] [--list] [--limit N] [--backtest-time <ms>]`.
- **`publicPost()` on `OkxRestClient`**: New unauthenticated POST method, symmetric with `publicGet`. Used internally by `market_get_indicator`.
- **`tgtCcy` parameter for place orders**: `spot_place_order`, `swap_place_order`, and `futures_place_order` now accept `tgtCcy`. Set `tgtCcy=quote_ccy` to specify order size in USDT instead of contracts/base currency.

### Fixed

- **CLI exits with code 1 on OKX business failure**: Write endpoints return HTTP 200 even when an order is rejected (e.g. `sCode="51008"`). The CLI now sets `process.exitCode = 1` when any item in the response has a non-zero `sCode`, making failures detectable by scripts and LLMs via exit code alone.
- **Friendly error for `config.toml` passphrase with special characters**: When a passphrase contains `#`, `\`, `"`, or `'`, the error now includes TOML quoting guidance instead of a cryptic parse error.
- **Insufficient balance errors now hint to check funding account**: Error codes `51008` (insufficient balance), `51119` (insufficient margin), and `51127` (insufficient available margin) now include a suggestion to check the funding account via `account_get_asset_balance` and transfer with `account_transfer (from=18, to=6)`.

### Changed

- **CLI output layer abstracted** (internal): Raw `process.stdout`/`stderr` writes unified behind an output abstraction. No user-facing behavior change.

---

## [1.2.5] - 2026-03-18

### Added

- **`dcd_subscribe` tool** (`earn.dcd`): atomic DCD subscription that requests a quote and executes it in a single step, eliminating quote-expiry race conditions for MCP users. Accepts optional `minAnnualizedYield` (in percent) — if the actual quote yield falls below this threshold, the order is rejected before execution. Returns the trade result with a quote snapshot (`annualizedYield`, `absYield`). Not supported in demo mode.
- **`dcd_redeem` tool** (`earn.dcd`): two-step early redemption designed for user confirmation before executing. First call (no `quoteId`): requests a redemption quote showing the early-exit cost. Second call (with `quoteId`): executes the redemption. If the quote has expired between the two calls, a fresh quote is automatically requested and executed atomically; response includes `autoRefreshedQuote: true`. Not supported in demo mode for the execute step.
- **CLI `okx diagnose --mcp`**: New MCP server troubleshooting mode. Checks package versions, Node.js compatibility, MCP entry-point existence and executability, Claude Desktop `mcpServers` configuration, recent MCP log tail, module-load smoke test (`--version`), and a live stdio JSON-RPC handshake (5 s timeout). Zero external dependencies — uses Node.js built-ins only.
- **`--output <file>` for `okx diagnose`**: Both the default and `--mcp` modes now accept `--output <path>` to save the diagnostic report to a file for sharing.
- **`allToolSpecs()` exported from `@agent-tradekit/core`**: The function is now part of the public API, exposed for future external consumers that need to enumerate all registered tool specs.

### Removed

- **Low-level DCD split tools removed**: `dcd_request_quote`, `dcd_execute_quote`, `dcd_request_redeem_quote`, and `dcd_execute_redeem` have been removed. Use `dcd_subscribe` for subscribe flows and `dcd_redeem` for early redemption flows.
- **`earn_get_lending_rate_summary` tool removed** (`earn.savings`): The lending market rate summary endpoint has been removed from the MCP tool set. Use `earn_get_lending_rate_history` to query market lending rates instead.

### Fixed

- **Tool description semantics for `rate` / `lendingRate` in Simple Earn tools**: Corrected misleading descriptions in `earn_get_savings_balance`, `earn_set_lending_rate`, `earn_get_lending_history`, and `earn_get_lending_rate_history`. The `rate` field is now clearly described as a *minimum lending rate threshold* (not market yield, not APY). The `lendingRate` field now documents the pro-rata dilution mechanism for stablecoins (USDT/USDC): when eligible supply exceeds borrowing demand, total interest is shared among all lenders so `lendingRate` < `rate`; for non-stablecoins, `lendingRate` equals `rate` with no dilution. Users should always use `lendingRate` as the true APY.
- **CLI `cancel` commands now support `--clOrdId`**: `okx spot/swap/futures cancel` previously required `--ordId` as a positional argument. Now accepts either `--ordId` or `--clOrdId` (client order ID); throws a clear error if neither is provided. Affects `spot_cancel_order`, `swap_cancel_order`, `futures_cancel_order`.
- **CLI `spot/swap/futures cancel` was ignoring `--instId` flag**: `cmdSpotCancel`, `cmdSwapCancel`, and `cmdFuturesCancel` used the positional argument (`rest[0]`) as `instId` instead of the `--instId` flag value, causing the cancel to silently use the wrong instrument ID. Fixed to correctly pass `v.instId`.

### Changed

- **Tool descriptions optimized across all modules**: Removed "Private endpoint", "Public endpoint", and "Rate limit" labels from all tool description strings to reduce MCP schema token overhead. Shortened descriptions for earn, grid, DCA, swap/futures/option modules. `[CAUTION]` markers preserved.
- **TWAP bot moved to CLI-only**: `bot.twap` MCP tools removed; TWAP functionality remains available via `okx bot twap` CLI commands.
- **`sanitize()` utility**: Masks UUIDs, long hex strings (≥32 chars), and Bearer tokens in diagnostic output before sharing.
- **`diagnose-utils.ts`** (internal): Shared `Report`, `ok`, `fail`, `section`, and `sanitize` helpers extracted from `diagnose.ts` to enable reuse by `diagnose-mcp.ts`.
- **File-level comments added** to all tools modules (internal documentation).

---

## [1.2.5-beta.5] - 2026-03-17

### Fixed

- **CLI `cancel` commands now support `--clOrdId`**: `okx spot/swap/futures cancel` previously required `--ordId` as a positional argument. Now accepts either `--ordId` or `--clOrdId` (client order ID); throws a clear error if neither is provided. Affects `spot_cancel_order`, `swap_cancel_order`, `futures_cancel_order`.

---

## [1.2.5-beta.4] - 2026-03-17

### Removed

- **`feat/add-more-bots-phase-1` reverted**: Removed all changes introduced by this branch, including bug fixes that are a side effect of the revert:
  - `dca_create_order` RSI trigger sub-parameters (`triggerCond`, `thold`, `timePeriod`, `timeframe`) and copy-trading params (`trackingMode`, `profitSharingRatio`)
  - 5 DCA CLI commands: `margin-add`, `margin-reduce`, `set-tp`, `set-reinvest`, `manual-buy`
  - Spot Recurring Buy CLI commands: `okx bot recurring create|amend|stop|orders|details|sub-orders`
  - `grid_create_order` 6 new optional parameters (`tpTriggerPx`, `slTriggerPx`, `algoClOrdId`, `tradeQuoteCcy`, `tpRatio`, `slRatio`)
  - 14 new grid CLI commands (`amend-basic-param`, `amend-order`, `close-position`, `cancel-close-order`, `instant-trigger`, `positions`, `withdraw-income`, `compute-margin-balance`, `margin-balance`, `adjust-investment`, `ai-param`, `min-investment`, `rsi-back-testing`, `max-quantity`)
  - TWAP CLI commands: `okx bot twap place|cancel|orders|details`
  - *(side effect)* **`swap_cancel_algo_orders` input format restored**: the branch had broken the input schema from `{ orders: [{ algoId, instId }] }` to flat `{ instId, algoId }`; revert restores correct format.
  - *(side effect)* **`dca_create_order` `pxStepsMult`/`volMult` threshold corrected**: the branch had misdocumented the required threshold as `maxSafetyOrds > 1`; revert restores correct `> 0`.

---

## [1.2.5-beta.3] - 2026-03-17

### Removed

- **`copytrading` module reverted**: Removed the 5 CLI copy-trading commands (`traders`, `trader-detail`, `status`, `follow`, `unfollow`), the `copytrading` MCP tool, related documentation (`docs/cli-reference.md` copytrading section), and README copy-trading entries introduced in v1.2.5-beta.2.

---

## [1.2.5-beta.2] - 2026-03-17

### Added

- **`dcd_subscribe` tool** (`earn.dcd`): atomic DCD subscription that requests a quote and executes it in a single step, eliminating quote-expiry race conditions for MCP users. Accepts optional `minAnnualizedYield` (in percent) — if the actual quote yield falls below this threshold, the order is rejected before execution. Returns the trade result with a quote snapshot (`annualizedYield`, `absYield`). Not supported in demo mode.
- **`dcd_redeem` tool** (`earn.dcd`): two-step early redemption designed for user confirmation before executing. First call (no `quoteId`): requests a redemption quote showing the early-exit cost. Second call (with `quoteId`): executes the redemption. If the quote has expired between the two calls, a fresh quote is automatically requested and executed atomically; response includes `autoRefreshedQuote: true`. Not supported in demo mode for the execute step.
- **Removed low-level split DCD tools**: `dcd_request_quote`, `dcd_execute_quote`, `dcd_request_redeem_quote`, and `dcd_execute_redeem` have been removed. Use `dcd_subscribe` for subscribe flows and `dcd_redeem` for early redemption flows.

### Changed

- **CLI `okx diagnose --mcp`**: New MCP server troubleshooting mode. Checks package versions, Node.js compatibility, MCP entry-point existence and executability, Claude Desktop `mcpServers` configuration, recent MCP log tail, module-load smoke test (`--version`), and a live stdio JSON-RPC handshake (5 s timeout). Zero external dependencies — uses Node.js built-ins only.
- **`--output <file>` for `okx diagnose`**: Both the default and `--mcp` modes now accept `--output <path>` to save the diagnostic report to a file for sharing.
- **`diagnose-utils.ts`** (internal): Shared `Report`, `ok`, `fail`, `section`, and `sanitize` helpers extracted from `diagnose.ts` to enable reuse by `diagnose-mcp.ts`.
- **`sanitize()` utility**: Masks UUIDs, long hex strings (≥32 chars), and Bearer tokens in diagnostic output before sharing.
- **`allToolSpecs()` exported from `@agent-tradekit/core`**: The function is now part of the public API, exposed for future external consumers that need to enumerate all registered tool specs (e.g. third-party MCP clients, testing utilities). It was already used internally by `buildTools()` and `createToolRunner()`; this change makes the export public-facing for anticipated downstream use, not for use within `diagnose-mcp.ts`.

---

## [1.2.4] - 2026-03-15

### Added

- **`market_get_stock_tokens` tool**: new dedicated tool to list stock token instruments (e.g. `AAPL-USDT-SWAP`, `TSLA-USDT-SWAP`). Fetches all instruments via `GET /api/v5/public/instruments` and filters client-side by `instCategory=3`. Supports `instType` (default `SWAP`) and optional `instId`. (#65)
- **CLI `okx market stock-tokens`**: new CLI sub-command mapping to `market_get_stock_tokens`. Usage: `okx market stock-tokens [--instType <SPOT|SWAP>] [--instId <id>] [--json]`. (#65)
- **Spot trailing stop support** (`spot_place_algo_order` with `ordType='move_order_stop'`): `spot_place_algo_order` now supports trailing stop orders in addition to conditional/oco. Pass `ordType='move_order_stop'` with `callbackRatio` (e.g. `'0.01'` for 1%) or `callbackSpread` (fixed price distance), and optionally `activePx`. (#67)
- **`swap_place_algo_order` now supports trailing stop** (`ordType='move_order_stop'`): extended with `callbackRatio`, `callbackSpread`, and `activePx` parameters, replacing the need for the deprecated `swap_place_move_stop_order` tool. (#67)
- **`spot_get_algo_orders` now includes trailing stop orders**: When no `ordType` filter is specified, the query now fetches `conditional`, `oco`, and `move_order_stop` orders in parallel. (#67)
- **CLI `okx spot algo trail`**: New CLI sub-command for placing a spot trailing stop order. Usage: `okx spot algo trail --instId BTC-USDT --side sell --sz 0.001 --callbackRatio 0.01 [--activePx <price>] [--tdMode cash]`. (#67)
- **CLI `okx futures algo trail`**: New CLI sub-command for placing a futures trailing stop order. Usage: `okx futures algo trail --instId BTC-USD-250328 --side sell --sz 1 --callbackRatio 0.01 [--activePx <price>] [--posSide <net|long|short>] [--tdMode <cross|isolated>] [--reduceOnly]`. (#68)
- **4 new option algo core tools** (`registerOptionAlgoTools`): `option_place_algo_order`, `option_amend_algo_order`, `option_cancel_algo_orders`, `option_get_algo_orders`. These let AI agents and users place conditional TP/SL algo orders on option positions, amend or cancel them, and query pending/historical option algo orders. (#72)
- **`option_place_order` now supports attached TP/SL** (`attachAlgoOrds`): Pass `--tpTriggerPx`/`--tpOrdPx` and/or `--slTriggerPx`/`--slOrdPx` to attach a take-profit or stop-loss algo order to the option order in one step. (#72)
- **CLI `okx option algo` commands**: `place`, `amend`, `cancel`, `orders` — full lifecycle management for option TP/SL algo orders. (#72)
- **7 new futures core tools** for delivery contract (Phase 1 feature parity with swap): `futures_amend_order`, `futures_close_position`, `futures_set_leverage`, `futures_get_leverage`, `futures_batch_orders`, `futures_batch_amend`, `futures_batch_cancel`. (#71)
- **5 new futures algo tools** (`registerFuturesAlgoTools`): `futures_place_algo_order`, `futures_place_move_stop_order`, `futures_amend_algo_order`, `futures_cancel_algo_orders`, `futures_get_algo_orders`. (#71)

### Fixed

- **Bot tools: added missing parameter descriptions for `algoId`, `algoOrdType`, and `groupId`** — Grid and DCA tools were missing `algoId` descriptions, causing AI agents to pass invalid values (error `51000`) or mismatched `algoOrdType` (error `50016`). Also added `groupId` for `grid_get_sub_orders` and `newSz` for `spot_amend_algo_order`.
- **CLI: `okx bot dca orders` now supports `--algoId` and `--instId` filters** — aligned with `okx bot grid orders` behavior.
- **`swap_get_algo_orders` hardcoded `instType`**: Now accepts an optional `instType` parameter (default `"SWAP"`, accepts `"FUTURES"`). (#71)
- **`callBackRatio` / `callBackSpread` parameter name mismatch**: Fixed capital-B parameter names in POST body for `swap_place_algo_order` and `swap_place_move_stop_order`. MCP input schema names remain unchanged. (#69)
- **CLI `algo place` missing trailing stop params**: `callbackRatio`, `callbackSpread`, and `activePx` were silently dropped in `cmdSpotAlgoPlace`, `cmdSwapAlgoPlace`, and `cmdFuturesAlgoPlace`. Now passed through correctly. (#74)
- **CLI `okx swap algo cancel` format**: Fixed `cmdSwapAlgoCancel` to wrap args as `{ orders: [{ instId, algoId }] }` matching the tool's required format. (#76)

### Deprecated

- **`swap_place_move_stop_order`**: Deprecated in favor of `swap_place_algo_order` with `ordType='move_order_stop'`. The tool remains functional for backward compatibility. (#67)

### Changed

- **`--modules all` now includes earn sub-modules**: `all` now expands to every module including `earn.savings`, `earn.onchain`, and `earn.dcd`. Default modules remain unchanged. (#66)
- **CLI: removed direct `smol-toml` dependency** — TOML functionality now provided exclusively through `@agent-tradekit/core`. (#39)
- **Deduplicate postinstall script**: `scripts/postinstall-notice.js` at monorepo root is the single source of truth; package copies are generated during `build`. (#50)
- **`earn` restructured as sub-module directory** (internal): `earn.ts` → `tools/earn/savings.ts`, `onchain-earn.ts` → `tools/earn/onchain.ts`. No public API changes. (#64)
- **Deduplicate `normalize()` across tool modules**: Removed 9 local copies; all now use shared `normalizeResponse` from `helpers.ts`. (#70)
- **Extract `buildAttachAlgoOrds()` helper**: Shared TP/SL assembly helper in `helpers.ts`, replacing 5 duplicate inline blocks. (#70)
- **Trim tool descriptions**: Removed "Private endpoint", "Public endpoint", and "Rate limit" labels from all tool descriptions to reduce MCP schema token overhead. `[CAUTION]` markers preserved. (#70)

---

## [1.2.4-beta.7] - 2026-03-14

### Fixed

- **CLI `okx swap algo cancel` reports "orders must be a non-empty array"**: `cmdSwapAlgoCancel` was passing `{ instId, algoId }` directly to `swap_cancel_algo_orders`, but the tool requires `{ orders: [{ instId, algoId }] }` format, causing the command to always fail. Fixed to match the wrapping pattern used by `futures`/`option`. (#76)

---

## [1.2.4-beta.6] - 2026-03-14

### Fixed

- **CLI `algo place` missing trailing stop params**: `cmdSpotAlgoPlace`, `cmdSwapAlgoPlace`, and `cmdFuturesAlgoPlace` were silently dropping `callbackRatio`, `callbackSpread`, and `activePx` when passed by the user. Placing a trailing stop via `okx {spot,swap,futures} algo place --ordType move_order_stop` would return API error 50015 (missing required param). The three params are now passed through to the tool runner correctly. (#74)

---

## [1.2.4-beta.5] - 2026-03-14

### Added

- **4 new option algo core tools** (`registerOptionAlgoTools`): `option_place_algo_order`, `option_amend_algo_order`, `option_cancel_algo_orders`, `option_get_algo_orders`. These let AI agents and users place conditional TP/SL algo orders on option positions, amend or cancel them, and query pending/historical option algo orders. (#72)
- **`option_place_order` now supports attached TP/SL** (`attachAlgoOrds`): Pass `--tpTriggerPx`/`--tpOrdPx` and/or `--slTriggerPx`/`--slOrdPx` to attach a take-profit or stop-loss algo order to the option order in one step. (#72)
- **CLI `okx option algo place`**: Place an option TP/SL algo order. Usage: `okx option algo place --instId BTC-USD-250328-95000-C --side sell --ordType oco --sz 1 --tdMode cross --tpTriggerPx 0.006 --tpOrdPx -1 --slTriggerPx 0.003 --slOrdPx -1`. (#72)
- **CLI `okx option algo amend`**: Amend an existing option algo order's TP/SL levels. Usage: `okx option algo amend --instId BTC-USD-250328-95000-C --algoId <id> [--newTpTriggerPx <p>] [--newSlTriggerPx <p>]`. (#72)
- **CLI `okx option algo cancel`**: Cancel an option algo order. Usage: `okx option algo cancel --instId BTC-USD-250328-95000-C --algoId <id>`. (#72)
- **CLI `okx option algo orders`**: List pending or historical option algo orders. Usage: `okx option algo orders [--instId <id>] [--history] [--ordType <conditional|oco>] [--json]`. (#72)

- **7 new futures core tools** for delivery contract (Phase 1 feature parity with swap): `futures_amend_order`, `futures_close_position`, `futures_set_leverage`, `futures_get_leverage`, `futures_batch_orders`, `futures_batch_amend`, `futures_batch_cancel`. These use futures-specific tool names (`futures_*`) instead of reusing swap tools, giving futures its own dedicated API surface. (#71)
- **5 new futures algo tools** (`registerFuturesAlgoTools`): `futures_place_algo_order`, `futures_place_move_stop_order`, `futures_amend_algo_order`, `futures_cancel_algo_orders`, `futures_get_algo_orders`. These are analogues of the swap algo tools but use `instType: "FUTURES"` and are registered under the `futures` module. (#71)

### Fixed

- **`swap_get_algo_orders` hardcoded `instType`**: The tool previously hardcoded `instType: "SWAP"` in the API request body, making it impossible to query FUTURES algo orders. Now accepts an optional `instType` parameter (default `"SWAP"`, accepts `"FUTURES"`). (#71)

### Changed

- **Deduplicate `normalize()` across tool modules**: Removed 9 local `normalize()` copies from `spot-trade`, `swap-trade`, `futures-trade`, `option-trade`, `algo-trade`, `account`, `market`, `bot/grid`, `bot/dca`; all now use the shared `normalizeResponse` from `helpers.ts`. (#70)
- **Extract `buildAttachAlgoOrds()` helper**: Moved the inline TP/SL assembly pattern (`tpTriggerPx`, `tpOrdPx`, `slTriggerPx`, `slOrdPx` → `attachAlgoOrds`) into a shared helper in `helpers.ts`, replacing 5 duplicate blocks in `spot_place_order`, `spot_batch_orders` (place), `swap_place_order`, `swap_batch_orders` (place), and `futures_place_order`. (#70)
- **Trim tool descriptions**: Removed "Private endpoint", "Public endpoint", and "Rate limit: X req/s per UID" labels from all tool description strings to reduce MCP schema token overhead. `[CAUTION]` markers are preserved. (#70)

### Fixed

- **`callBackRatio` / `callBackSpread` parameter name mismatch**: OKX API expects `callBackRatio` and `callBackSpread` (capital B) but the POST body was sending `callbackRatio` and `callbackSpread` (lowercase b), causing sCode 50015 errors. Fixed in `swap_place_algo_order` and `swap_place_move_stop_order` handlers. The MCP input schema parameter names (`callbackRatio` / `callbackSpread`) remain unchanged. (#69)

---

## [1.2.4-beta.4] - 2026-03-14

### Added

- **`market_get_stock_tokens` tool**: new dedicated tool to list stock token instruments (e.g. `AAPL-USDT-SWAP`, `TSLA-USDT-SWAP`). Fetches all instruments via `GET /api/v5/public/instruments` and filters client-side by `instCategory=3`. Supports `instType` (default `SWAP`) and optional `instId`. (#65)
- **CLI `okx market stock-tokens`**: new CLI sub-command mapping to `market_get_stock_tokens`. Usage: `okx market stock-tokens [--instType <SPOT|SWAP>] [--instId <id>] [--json]`. (#65)
- **Spot trailing stop support** (`spot_place_algo_order` with `ordType='move_order_stop'`): `spot_place_algo_order` now supports trailing stop orders in addition to conditional/oco. Pass `ordType='move_order_stop'` with `callbackRatio` (e.g. `'0.01'` for 1%) or `callbackSpread` (fixed price distance), and optionally `activePx`. (#67)
- **`swap_place_algo_order` now supports trailing stop** (`ordType='move_order_stop'`): extended with the same `callbackRatio`, `callbackSpread`, and `activePx` parameters, replacing the need for the deprecated `swap_place_move_stop_order` tool. (#67)
- **`spot_get_algo_orders` now includes trailing stop orders**: When no `ordType` filter is specified, the query now fetches `conditional`, `oco`, and `move_order_stop` orders in parallel. (#67)
- **CLI `okx spot algo trail`**: New CLI sub-command for placing a spot trailing stop order. Usage: `okx spot algo trail --instId BTC-USDT --side sell --sz 0.001 --callbackRatio 0.01 [--activePx <price>] [--tdMode cash]`. (#67)
- **CLI `okx futures algo trail`**: New CLI sub-command for placing a futures trailing stop order. Usage: `okx futures algo trail --instId BTC-USD-250328 --side sell --sz 1 --callbackRatio 0.01 [--activePx <price>] [--posSide <net|long|short>] [--tdMode <cross|isolated>] [--reduceOnly]`. (#68)

### Fixed

- **Bot tools: added missing parameter descriptions for `algoId`, `algoOrdType`, and `groupId`** — Grid tools (`grid_get_orders`, `grid_get_order_details`, `grid_get_sub_orders`, `grid_stop_order`) and DCA tools (`dca_get_orders`, `dca_get_order_details`) were missing `algoId` descriptions, causing AI agents to pass invalid values (error `51000`) or mismatched `algoOrdType` (error `50016`). Also added `groupId` description for `grid_get_sub_orders` and `newSz` description for `spot_amend_algo_order`.
- **CLI: `okx bot dca orders` now supports `--algoId` and `--instId` filters** — Previously the CLI did not pass these parameters to the underlying `dca_get_orders` tool, even though the MCP tool already supported them. Now aligned with `okx bot grid orders` behavior.

### Deprecated

- **`swap_place_move_stop_order`**: Deprecated in favor of `swap_place_algo_order` with `ordType='move_order_stop'`. The tool remains functional for backward compatibility. (#67)

### Changed

- **`--modules all` now includes earn sub-modules**: `all` now expands to every module including `earn.savings`, `earn.onchain`, and `earn.dcd`, on par with bot sub-modules. Previously, earn required explicit opt-in via `all,earn`. The default modules remain unchanged. (#66)
- **CLI: removed direct `smol-toml` dependency** — `packages/cli` no longer declares `smol-toml` as a direct dependency. The TOML functionality is now provided exclusively through `@agent-tradekit/core`. (#39)
- **Deduplicate postinstall script**: `scripts/postinstall-notice.js` at monorepo root is now the single source of truth. The copies in `packages/cli/scripts/postinstall.js` and `packages/mcp/scripts/postinstall.js` are generated during `build` and ignored by git. (#50)
- **`earn` restructured as sub-module directory** (internal): `earn.ts` → `tools/earn/savings.ts`, `onchain-earn.ts` → `tools/earn/onchain.ts`, with a new `tools/earn/index.ts` aggregator. No public API changes. (#64)

---

## [1.2.4-beta.3] - 2026-03-13

### Added

- **CLI `okx futures algo trail`**: New CLI sub-command for placing a futures trailing stop order. Usage: `okx futures algo trail --instId BTC-USD-250328 --side sell --sz 1 --callbackRatio 0.01 [--activePx <price>] [--posSide <net|long|short>] [--tdMode <cross|isolated>] [--reduceOnly]`. (#68)

---

## [1.2.4-beta.2] - 2026-03-13

### Added

- **Spot trailing stop support** (`spot_place_algo_order` with `ordType='move_order_stop'`): `spot_place_algo_order` now supports trailing stop orders in addition to conditional/oco. Pass `ordType='move_order_stop'` with `callbackRatio` (e.g. `'0.01'` for 1%) or `callbackSpread` (fixed price distance), and optionally `activePx`. (#67)
- **`swap_place_algo_order` now supports trailing stop** (`ordType='move_order_stop'`): The swap algo order tool is extended with the same `callbackRatio`, `callbackSpread`, and `activePx` parameters, replacing the need for the deprecated `swap_place_move_stop_order` tool. (#67)
- **`spot_get_algo_orders` now includes trailing stop orders**: When no `ordType` filter is specified, the query now fetches `conditional`, `oco`, and `move_order_stop` orders in parallel (previously only `conditional` and `oco`). (#67)
- **CLI `okx spot algo trail`**: New CLI sub-command for placing a spot trailing stop order. Usage: `okx spot algo trail --instId BTC-USDT --side sell --sz 0.001 --callbackRatio 0.01 [--activePx <price>] [--tdMode cash]`. (#67)

### Deprecated

- **`swap_place_move_stop_order`**: Deprecated in favor of `swap_place_algo_order` with `ordType='move_order_stop'`. The tool remains functional for backward compatibility. (#67)

### Changed

- **`--modules all` now includes earn sub-modules**: `all` now expands to every module including `earn.savings`, `earn.onchain`, and `earn.dcd`, on par with bot sub-modules. Previously, earn required explicit opt-in via `all,earn`. The default modules remain unchanged (`spot`, `swap`, `option`, `account`, `bot.grid`). (#66)

---

## [1.2.4-beta.1] - 2026-03-13

### Added

- **`market_get_stock_tokens` tool**: new dedicated tool to list stock token instruments (e.g. `AAPL-USDT-SWAP`, `TSLA-USDT-SWAP`). Fetches all instruments via `GET /api/v5/public/instruments` and filters client-side by `instCategory=3`. Supports `instType` (default `SWAP`) and optional `instId`. (#65)
- **CLI `okx market stock-tokens`**: new CLI sub-command mapping to `market_get_stock_tokens`. Usage: `okx market stock-tokens [--instType <SPOT|SWAP>] [--instId <id>] [--json]`.
- **DCD module** (`earn.dcd`) — 8 new MCP tools and 10 CLI commands for OKX Dual Currency Deposit (双币赢): `dcd_get_currency_pairs`, `dcd_get_products`, `dcd_request_quote`, `dcd_execute_quote`, `dcd_request_redeem_quote`, `dcd_execute_redeem`, `dcd_get_order_state`, `dcd_get_orders`. CLI: `okx earn dcd pairs`, `products`, `quote`, `buy`, `quote-and-buy`, `redeem-quote`, `redeem`, `redeem-execute`, `order`, `orders`. Supports client-side product filtering (`--minYield`, `--strikeNear`, `--termDays`, `--expDate`), two-step early redemption flow, and demo-mode guard on all write operations.

### Fixed

- **Bot tools: added missing parameter descriptions for `algoId`, `algoOrdType`, and `groupId`** — Grid tools (`grid_get_orders`, `grid_get_order_details`, `grid_get_sub_orders`, `grid_stop_order`) and DCA tools (`dca_get_orders`, `dca_get_order_details`) were missing `algoId` descriptions, causing AI agents to pass invalid values (error `51000`) or mismatched `algoOrdType` (error `50016`). Also added `groupId` description for `grid_get_sub_orders` and `newSz` description for `spot_amend_algo_order`.
- **CLI: `okx bot dca orders` now supports `--algoId` and `--instId` filters** — Previously the CLI did not pass these parameters to the underlying `dca_get_orders` tool, even though the MCP tool already supported them. Now aligned with `okx bot grid orders` behavior.

### Changed

- **CLI: removed direct `smol-toml` dependency** — `packages/cli` no longer declares `smol-toml` as a direct dependency. The TOML functionality is now provided exclusively through `@agent-tradekit/core`, which bundles `smol-toml` internally. (#39)
- **Deduplicate postinstall script**: `scripts/postinstall-notice.js` at monorepo root is now the single source of truth. The copies in `packages/cli/scripts/postinstall.js` and `packages/mcp/scripts/postinstall.js` are generated during `build` and ignored by git. (#50)
- **`earn` restructured as sub-module directory** (internal): `earn.ts` → `tools/earn/savings.ts`, `onchain-earn.ts` → `tools/earn/onchain.ts`, with a new `tools/earn/index.ts` aggregator. Consistent with the `bot/` sub-module directory pattern. No public API changes. (#64)

---

## [1.2.4-beta.0] - 2026-03-13

### Added

- **`market_get_stock_tokens` tool**: new dedicated tool to list stock token instruments (e.g. `AAPL-USDT-SWAP`, `TSLA-USDT-SWAP`). Fetches all instruments via `GET /api/v5/public/instruments` and filters client-side by `instCategory=3`. Supports `instType` (default `SWAP`) and optional `instId`. (#65)
- **CLI `okx market stock-tokens`**: new CLI sub-command mapping to `market_get_stock_tokens`. Usage: `okx market stock-tokens [--instType <SPOT|SWAP>] [--instId <id>] [--json]`.

### Fixed

- **Bot tools: added missing parameter descriptions for `algoId`, `algoOrdType`, and `groupId`** — Grid tools (`grid_get_orders`, `grid_get_order_details`, `grid_get_sub_orders`, `grid_stop_order`) and DCA tools (`dca_get_orders`, `dca_get_order_details`) were missing `algoId` descriptions, causing AI agents to pass invalid values (error `51000`) or mismatched `algoOrdType` (error `50016`). Also added `groupId` description for `grid_get_sub_orders` and `newSz` description for `spot_amend_algo_order`.
- **CLI: `okx bot dca orders` now supports `--algoId` and `--instId` filters** — Previously the CLI did not pass these parameters to the underlying `dca_get_orders` tool, even though the MCP tool already supported them. Now aligned with `okx bot grid orders` behavior.

### Changed

- **CLI: removed direct `smol-toml` dependency** — `packages/cli` no longer declares `smol-toml` as a direct dependency. The TOML functionality is now provided exclusively through `@agent-tradekit/core`, which bundles `smol-toml` internally. (#39)
- **Deduplicate postinstall script**: `scripts/postinstall-notice.js` at monorepo root is now the single source of truth. The copies in `packages/cli/scripts/postinstall.js` and `packages/mcp/scripts/postinstall.js` are generated during `build` and ignored by git. (#50)
- **`earn` restructured as sub-module directory** (internal): `earn.ts` → `tools/earn/savings.ts`, `onchain-earn.ts` → `tools/earn/onchain.ts`, with a new `tools/earn/index.ts` aggregator. Consistent with the `bot/` sub-module directory pattern. No public API changes. (#64)

---

## [1.2.3] - 2026-03-12

### Breaking Changes

- **`--modules all` no longer includes earn sub-modules**: Previously, `--modules all` expanded to every module including `earn.savings` and `earn.onchain`. Now `all` only includes base modules and bot sub-modules. To enable earn modules, you must opt in explicitly:
  - `--modules all,earn` — all modules + all earn sub-modules
  - `--modules all,earn.savings` — all modules + Simple Earn only
  - `--modules all,earn.onchain` — all modules + On-chain Earn only
  - `--modules earn` — earn sub-modules only

  **Migration**: if you previously used `--modules all` and relied on earn tools being active, add `,earn` to your configuration: `--modules all,earn`.

### Added

- **DCD module** (`earn.dcd`) — 8 new MCP tools and 10 CLI commands for OKX Dual Currency Deposit (双币赢): `dcd_get_currency_pairs`, `dcd_get_products`, `dcd_request_quote`, `dcd_execute_quote`, `dcd_request_redeem_quote`, `dcd_execute_redeem`, `dcd_get_order_state`, `dcd_get_orders`. CLI: `okx earn dcd pairs`, `products`, `quote`, `buy`, `quote-and-buy`, `redeem-quote`, `redeem`, `redeem-execute`, `order`, `orders`. Supports client-side product filtering (`--minYield`, `--strikeNear`, `--termDays`, `--expDate`), two-step early redemption flow, and demo-mode guard on all write operations.
- **HTTP/HTTPS proxy support**: Configure `proxy_url` in your TOML profile to route all OKX API requests through a proxy server. Supports authenticated proxies via URL credentials (e.g. `http://user:pass@proxy:8080`). Only HTTP/HTTPS proxies are supported; SOCKS is not. (#53)
- **CLI `--verbose` flag**: Add `--verbose` to any command to see detailed network request/response info on stderr — method, URL, auth status (key masked), timing, HTTP status, OKX code, and trace ID. Useful for debugging connectivity and auth issues.
- **CLI `okx diagnose` command**: Step-by-step connectivity check that verifies environment (Node.js, OS, shell, locale, timezone, proxy), configuration (credentials, site, base URL), network (DNS → TCP → TLS → public API), and authentication. On failure, shows actionable hints. Prints a copy-paste diagnostic report block for sharing with support.
- **CLI place commands — attached TP/SL**: `okx spot place`, `okx swap place`, and `okx futures place` now accept optional take-profit and stop-loss parameters: `--tpTriggerPx`, `--tpOrdPx`, `--tpTriggerPxType`, `--slTriggerPx`, `--slOrdPx`, `--slTriggerPxType`. These are forwarded directly to the OKX order API as attached TP/SL on the placed order.
- **Earn module** — 7 new tools for OKX Simple Earn (savings/flexible lending): `earn_get_savings_balance`, `earn_savings_purchase`, `earn_savings_redeem`, `earn_set_lending_rate`, `earn_get_lending_history`, `earn_get_lending_rate_summary`, `earn_get_lending_rate_history`. Includes CLI commands, dual-language documentation, and full test coverage.

---

## [1.2.0] - 2026-03-10

### Added

- **Contract DCA — optional parameters**: `--slMode` (stop-loss price type: `limit`/`market`), `--allowReinvest` (reinvest profit into next cycle, default `true`), `--triggerStrategy` (bot start mode: `instant`/`price`/`rsi`), `--triggerPx` (trigger price for `price` strategy). All are optional and only apply to contract DCA create.
- **Contract DCA orders — `instId` filter**: `dca_get_orders` now accepts an optional `--instId` parameter to filter contract DCA bots by instrument (e.g. `BTC-USDT-SWAP`)
- **Contract DCA sub-orders — `cycleId` filter**: `dca_get_sub_orders` now accepts an optional `--cycleId` parameter, allowing querying orders within a specific cycle
- **On-chain Earn module (6 tools)**: new `onchain-earn` module for OKX On-chain Earn (staking/DeFi) products — `onchain_earn_get_offers`, `onchain_earn_purchase`, `onchain_earn_redeem`, `onchain_earn_cancel`, `onchain_earn_get_active_orders`, `onchain_earn_get_order_history`. CLI: `okx earn onchain offers`, `okx earn onchain purchase`, `okx earn onchain redeem`, `okx earn onchain cancel`, `okx earn onchain orders`, `okx earn onchain history`.

### Changed

- **DCA tools now contract-only**: Removed Spot DCA support from all 5 DCA tools (`dca_create_order`, `dca_stop_order`, `dca_get_orders`, `dca_get_order_details`, `dca_get_sub_orders`). The `type` parameter has been removed — all DCA tools now operate exclusively on contract DCA. Spot DCA was removed due to product risk assessment.
- **Agent skill (`okx-cex-bot`) updated for contract-only DCA**: Rewrote `SKILL.md` to remove all Spot DCA references — description, quickstart examples, command index, cross-skill workflows, operation flow, CLI reference (create/stop/orders/details/sub-orders), MCP tool reference, input/output examples, edge cases, and parameter display name tables. DCA sections now document contract-only usage with `--lever`, `--direction` as required params and no `--type` flag.
- **All order placement tools — `tag` parameter removed, auto-injected**: the `tag` field has been removed from all order placement tool input schemas (spot, swap, futures, option, algo, grid). The server now automatically injects `tag: "MCP"` (or `"CLI"` for CLI usage) into every outgoing order request. Users who previously passed a custom `tag` value will no longer be able to override it. Note: DCA bot tools do not inject `tag` as the Contract DCA API does not support this field.

### Fixed

- **Contract DCA `side`/`direction` mismatch** (critical): MCP schema used `side` (`buy`/`sell`) but API requires `direction` (`long`/`short`). The `side` field was removed; `direction` is now used directly. Previously, short positions could not be created correctly.
- **Contract DCA `safetyOrdAmt`, `pxSteps`, `pxStepsMult`, `volMult` conditionally required**: These 4 parameters are business-required when `maxSafetyOrds > 0` (API returns 400 if omitted), but API-optional when `maxSafetyOrds = 0`. They are now schema-optional with descriptions noting the conditional requirement.
- **Contract sub-orders sent unsupported pagination**: contract DCA orders-by-cycle path sent `after`/`before` params, but the API only supports `limit`. Removed `after`/`before` from this path.

---

## [1.1.9] - 2026-03-09

### Changed

- **Spot DCA endpoint paths updated**: all 5 Spot DCA tool endpoints now use the new `/api/v5/tradingBot/spot-dca` base URL and renamed paths (`create`, `stop`, `bot-active-list`, `bot-history-list`, `bot-detail`, `trade-list`), aligning with the backend change in okcoin-bots MR #210. Contract DCA remains on `/api/v5/tradingBot/dca` and is unaffected.
- **`grid_create_order` — `sz` description clarified**: the `sz` parameter description now says "investment amount in margin currency (e.g. USDT for USDT-margined contracts)" instead of "Investment amount in USDT", correctly covering both USDT-margined and coin-margined contract grids. Behavior is unchanged.
- **`--no-basePos` CLI example removed from docs**: the `--no-basePos` flag example has been removed from `docs/cli-reference.md` as `basePos` defaults to `true` and is not exposed as a standalone CLI flag.

### Fixed

- **`dca_create_order` — contract DCA now passes `slPct` and `slMode`**: the `slPct` (stop-loss ratio) and `slMode` (stop-loss price type) parameters were accepted in the schema but not forwarded to the OKX API for contract DCA. This caused stop-loss settings to be silently ignored when creating contract DCA bots. Spot DCA was unaffected. Note: when `slPct` is set for contract DCA, `slMode` (`"limit"` or `"market"`) is required by the OKX API.

---

## [1.1.8] - 2026-03-09

### Changed

- **`grid_create_order` — `basePos` defaults to `true`**: contract grid bots now open a base position by default (long/short direction). Neutral direction ignores this parameter. Pass `basePos: false` (MCP) or `--no-basePos` (CLI) to disable. Spot grid is unaffected.

---

## [1.1.7] - 2026-03-09

### Changed

- Version bump.

---

## [1.1.6] - 2026-03-08

### Changed

- Version bump.

---

## [1.1.5] - 2026-03-08

### Added

- **Multi-level `--help` navigation**: `okx --help`, `okx <module> --help`, and `okx <module> <subgroup> --help` now print scoped help with per-command descriptions, so AI agents can discover available capabilities without reading source code.

### Fixed

- **`--reserveFunds` missing from `bot dca create` help**: the parameter was supported in code but absent from the help output.

---

## [1.1.4] - 2026-03-08

### Fixed

- **`--modules all` now includes `bot.dca`**: previously `all` expanded using `BOT_DEFAULT_SUB_MODULES` (bot.grid only), silently excluding the DCA module. Now correctly uses all bot sub-modules.
- **`option` added to default modules**: the default module set is now `spot, swap, option, account, bot.grid`. MCP server help text updated to match actual defaults.

---

## [1.1.3] - 2026-03-08

### Added

- **Git hash in `--version` output**: both CLI and MCP server now display the build commit hash alongside the version, e.g. `1.1.3 (abc1234)`, making it easy to verify which exact commit a published package was built from

### Fixed

- **Spot `tdMode` not configurable**: `okx spot place`, `okx spot algo place` (TP/SL), MCP `spot_place_algo_order`, and MCP `spot_batch_orders` previously hardcoded `tdMode` with no way to override it. The `--tdMode` flag is now exposed as an optional parameter (default: `cash` for non-margin accounts). Users on unified/margin accounts can pass `--tdMode cross`.

---

## [1.1.2] - 2026-03-08

### Added

- **One-line install scripts**: `install.sh` (macOS/Linux) and `install.ps1` (Windows) — install MCP server + CLI and auto-configure detected MCP clients in one command
- **Auto MCP client configuration**: install script detects and configures Claude Code, Claude Desktop, Cursor, VS Code, and Windsurf automatically
- **`config init --lang`**: `--lang zh` flag for Chinese-language interactive wizard; defaults to English
- **Smart default profile name**: `config init` infers a sensible default profile name from the environment
- **CLI option module**: `okx option` commands for placing, cancelling, amending orders, querying positions, fills, instruments, and Greeks
- **CLI batch operations**: `okx spot batch` and `okx swap batch` for bulk place/cancel/amend
- **CLI audit log**: `okx trade history` to query the local NDJSON audit log
- **CLI contract DCA**: `okx bot dca contract` commands with `--type` flag to distinguish spot vs. contract DCA

### Fixed

- **Version reporting**: MCP server now reads its version from `package.json` at runtime instead of a hardcoded string
- **`okx setup` npx command**: setup config for standalone MCP clients (Claude Desktop, Cursor) now uses `npx` so users don't need a global install
- **Bot write endpoints**: `sCode`/`sMsg` errors from grid and DCA write endpoints are now surfaced correctly instead of being silently swallowed
- **Install script**: installs both `@okx_ai/okx-trade-mcp` and `@okx_ai/okx-trade-cli` (previously only installed one package)

### Changed

- **Bot sub-module refactor**: `bot` module now includes a `bot.default` sub-module; internal sub-module loading is unified and more robust
- **Docs**: one-line install instructions moved from READMEs to `docs/configuration.md`

---

## [1.1.1] - 2026-03-07

### Fixed

- **Build**: `smol-toml` was not bundled into the CLI output despite `noExternal` config — npm registry `1.1.0` shipped with an external `import from "smol-toml"` that fails at runtime. Added `smol-toml` to runtime `dependencies` as a reliable fix and bumped version to republish.

---

## [1.1.0] - 2026-03-07

### Added

- **Contract DCA bot**: `bot.dca` submodule now supports contract (perpetual) DCA in addition to spot — new tools `dca_get_contract_orders`, `dca_get_contract_order_details`, `dca_create_contract_order`, `dca_stop_contract_order`
- **`okx setup` subcommand**: interactive wizard to generate and insert MCP server config into Claude Code, VS Code, Windsurf, and other MCP clients
- **CLI `--version` / `-v` flag**: print the current package version and exit
- **CLI `swap amend` command**: amend an open swap order via the CLI (`okx swap amend`)

### Fixed

- **Duplicate tool**: removed duplicate `swap_amend_order` tool registration that caused the tool to appear twice in tool listings
- **CLI swap amend dispatch**: `okx swap amend` now correctly dispatches to the swap handler instead of the spot handler

### Changed

- **`bot.dca` is opt-in**: the DCA submodule is no longer loaded by default; enable it with `--modules bot.dca` or by adding `bot.dca` to the `modules` list in `~/.okx/config.toml`
- **Bot tools reorganized into submodules**: `bot` module now uses a submodule system — `bot.grid` and `bot.dca` can be loaded independently
- **CLI architecture**: CLI commands now invoke Core tool handlers directly via `ToolRunner`, reducing duplication between MCP and CLI code paths

---

## [1.0.9] - 2026-03-06

### Fixed

- **algo orders**: `swap_get_algo_orders` and `spot_get_algo_orders` now pass the required `state` parameter when querying history (`/api/v5/trade/orders-algo-history`), defaulting to `effective` (#28)

---

## [1.0.8] - 2026-03-06

### Changed

- **npm org rename**: packages moved from `@okx_retail` to `@okx_ai` scope. Please reinstall:
  ```
  npm uninstall -g @okx_retail/okx-trade-mcp @okx_retail/okx-trade-cli
  npm install -g @okx_ai/okx-trade-mcp @okx_ai/okx-trade-cli
  ```
  Binary names are unchanged — `okx-trade-mcp` and `okx` still work after reinstall.

---

## [1.0.7] - 2026-03-04

### Added

- **Scenario tests**: added `scripts/scenario-test/` with multi-step integration tests covering stateless read flows (account balance, market data, swap leverage) and stateful write flows (Spot place→query→cancel, Swap set-leverage→place→query→cancel). Stateless scenarios are CI-safe; stateful scenarios require `OKX_DEMO=1`.
- **Multi-site support**: users on OKX Global (`www.okx.com`), EEA (`my.okx.com`), and US (`app.okx.com`) can now configure their site via `--site <global|eea|us>` CLI flag, `OKX_SITE` env var, or `site` field in `~/.okx/config.toml`. The API base URL is automatically derived from the site; explicit `OKX_API_BASE_URL` / `base_url` overrides remain supported for advanced use.
- **`config init` site selection**: the interactive wizard now prompts for site before asking for API key, and opens the correct API management URL for the chosen site.
- **`config show` site display**: the `site` field is now shown for each profile.
- **Region error context**: error suggestions for OKX region-restriction codes (51155, 51734) now include the currently configured site to help users diagnose misconfigured site settings.
- **docs/faq.md**: added "General" section with 3 new Q&As — "What is OKX Trade MCP?", "What trading pairs are supported?", and "What risks should I understand?" (bilingual EN + ZH)
- **docs/faq.md**: added "API Coverage" section explaining which OKX REST API modules are supported vs. not yet supported by the MCP server and CLI (bilingual EN + ZH)

### Fixed

- **CLI**: ensure `main()` is always invoked when executed via npm global symlink; add defensive comment and symlink regression test to prevent future regressions (#21)

### Changed

- **Release prep**: version bump for publish
- **`okx config init`**: site selection (Global / EEA / US) and demo/live choice are now asked upfront; the CLI opens the targeted API creation page with `?go-demo-trading=1` or `?go-live-trading=1` query param so users land directly on the correct tab. EEA (`my.okx.com`) and US (`app.okx.com`) sites are supported and saved as `base_url` in the profile.
- **docs/configuration.md**, **README.md**, **README.zh.md**: updated API key creation links to direct URLs with `?go-demo-trading=1` / `?go-live-trading=1` parameters (bilingual EN + ZH).
- **npm scope**: packages are now published under the `@okx_retail` organisation. Please reinstall:
  ```
  npm uninstall -g okx-trade-mcp okx-trade-cli
  npm install -g @okx_retail/okx-trade-mcp @okx_retail/okx-trade-cli
  ```
  Binary names are unchanged — `okx-trade-mcp` and `okx` still work after reinstall.

---

## [1.0.6] - 2026-03-04

### Added

### Fixed

### Changed

- **Project rename**: internal package `@okx-hub/core` renamed to `@agent-tradekit/core`

---

## [1.0.5] - 2026-03-04

### Added

- **Option module (10 tools)**: new `option` module for options trading — `option_place_order`, `option_cancel_order`, `option_batch_cancel`, `option_amend_order` (write); `option_get_order`, `option_get_orders`, `option_get_positions` (with Greeks), `option_get_fills`, `option_get_instruments` (option chain), `option_get_greeks` (IV + Delta/Gamma/Theta/Vega) (read)

### Fixed

### Changed

- Total tools: 48 → 57 → 67
- **Documentation restructure**: split single `README.md` into `README.md` (EN) + `README.zh.md` (ZH) with language toggle; added `docs/configuration.md` (all client setups + startup scenarios), `docs/faq.md`, `docs/cli-reference.md`, and per-module references under `docs/modules/`
- **GitHub issue templates**: added `bug_report.md` and `feature_request.md` under `.github/ISSUE_TEMPLATE/`
- **`SECURITY.md`**: added supported versions table and GitHub Private Security Advisory link
- **Error handling — actionable suggestions**: `OkxRestClient` now maps ~20 OKX error codes to retry guidance; rate-limit codes (`50011`, `50061`) throw `RateLimitError`; server-busy codes carry "Retry after X seconds"; region/compliance and account-issue codes carry "Do not retry" advice
- **Test coverage**: function coverage raised from 76.5% → 93.4% (199 → 243 tests); every source file now exceeds 80% function coverage
- **Coverage scripts**: c8 now includes `packages/cli/src` and `packages/mcp/src` in coverage collection and runs all package tests

---

## [1.0.4] - 2026-03-03

### Added

- **Audit log — `trade_get_history`**: query the local NDJSON audit log of all MCP tool calls; supports `limit`, `tool`, `level`, and `since` filters
- **Audit logging**: MCP server automatically writes NDJSON entries to `~/.okx/logs/trade-YYYY-MM-DD.log`; `--no-log` disables logging, `--log-level` sets the minimum level (default `info`); sensitive fields (apiKey, secretKey, passphrase) are automatically redacted
- **Error tracing**: `traceId` field added to `ToolErrorPayload` and all error classes — populated from `x-trace-id` / `x-request-id` response headers when OKX returns them
- **Server version in MCP errors**: `serverVersion` injected into MCP error payloads for easier bug reporting
- **CLI version in errors**: `Version: okx-trade-cli@x.x.x` always printed to stderr on error; `TraceId:` printed when available
- **Market — index data**: `market_get_index_ticker`, `market_get_index_candles` (+ history), `market_get_price_limit` (3 new tools)
- **Spot — batch orders**: `spot_batch_orders` — batch place/cancel/amend up to 20 spot orders in one request
- **Spot/Swap — order archive**: `status="archive"` on `spot_get_orders` / `swap_get_orders` → `/trade/orders-history-archive` (up to 3 months)
- **Account — positions**: `account_get_positions` — cross-instType positions query (MARGIN/SWAP/FUTURES/OPTION)
- **Account — bills archive**: `account_get_bills_archive` — archived ledger up to 3 months
- **Account — sizing**: `account_get_max_withdrawal`, `account_get_max_avail_size`
- **README**: "Reporting Issues / 报错反馈" section with example error payloads
- **Grid Bot (module: `bot`)**: 5 new tools for OKX Trading Bot grid strategies — `grid_get_orders`, `grid_get_order_details`, `grid_get_sub_orders` (read), `grid_create_order`, `grid_stop_order` (write). Covers Spot Grid, Contract Grid, and Moon Grid.
- **CLI `--demo` flag**: global `--demo` option to enable simulated trading mode directly from the command line (alternative to `OKX_DEMO=1` env var or profile config)
- **CLI bot grid commands**: `bot grid orders`, `bot grid details`, `bot grid sub-orders`, `bot grid create`, `bot grid stop` — full grid bot lifecycle management via CLI
- **CLI full coverage**: extended `okx-trade-cli` to cover all 57 MCP tools — new commands across `market` (`instruments`, `funding-rate`, `mark-price`, `trades`, `index-ticker`, `index-candles`, `price-limit`, `open-interest`), `account` (`positions`, `bills`, `fees`, `config`, `set-position-mode`, `max-size`, `max-avail-size`, `max-withdrawal`, `positions-history`, `asset-balance`, `transfer`), `spot` (`get`, `amend`), `swap` (`get`, `fills`, `close`, `get-leverage`), and new `futures` module (`orders`, `positions`, `fills`, `place`, `cancel`, `get`)
- **CLI/MCP entry tests**: new unit tests for `okx` and `okx-trade-mcp` entrypoints to exercise help/setup flows and keep coverage accurate

### Fixed

- **Grid bot endpoint paths**: corrected all 5 grid tool endpoints to match OKX API v5 spec — `orders-algo-pending`, `orders-algo-history`, `order-algo`, `stop-order-algo` (previously used wrong paths causing HTTP 404)
- **`grid_stop_order`**: request body now serialized as an array `[{...}]` as required by OKX `stop-order-algo` endpoint
- **`grid_create_order`**: removed spurious `tdMode` parameter (field does not exist in `ApiPlaceGridParam`; was silently ignored by server but polluted the tool schema)
- **`grid_create_order`**: restricted `algoOrdType` enum to `["grid", "contract_grid"]` — server `@StringMatch` validation only accepts these two values for creation; `moon_grid` is valid for queries and stop operations only
- **`grid_stop_order`**: expanded `stopType` enum from `["1","2"]` to `["1","2","3","5","6"]` to match server `StopStrategyParam` validation
- **CLI `bot grid create`**: removed `--tdMode` flag and `algoOrdType` now restricted to `<grid|contract_grid>`, in sync with MCP tool changes
- **CLI `bot grid stop`**: updated `--stopType` hint to `<1|2|3|5|6>`
- **`spot_get_algo_orders`**: fixed `400 Parameter ordType error` when called without an `ordType` filter — now fetches `conditional` and `oco` types in parallel and merges results, matching the behaviour of `swap_get_algo_orders`

### Changed

---

## [1.0.2] - 2026-03-01

### Added

- **Market — 5 new tools**: `market_get_instruments`, `market_get_funding_rate` (+ history), `market_get_mark_price`, `market_get_trades`, `market_get_open_interest`
- **Market — candle history**: `history=true` on `market_get_candles` → `/market/history-candles`
- **Spot/Swap — fills archive**: `archive=true` on `spot_get_fills` / `swap_get_fills` → `/trade/fills-history`
- **Spot/Swap — single order fetch**: `spot_get_order`, `swap_get_order` — fetch by `ordId` / `clOrdId`
- **Swap — close & batch**: `swap_close_position`, `swap_batch_orders` (batch place/cancel/amend up to 20)
- **Swap — leverage query**: `swap_get_leverage`
- **Account — 6 new tools**: `account_get_bills`, `account_get_positions_history`, `account_get_trade_fee`, `account_get_config`, `account_set_position_mode`, `account_get_max_size`
- **Account — funding balance**: `account_get_asset_balance` (funding account, `/asset/balances`)
- **System capabilities tool**: `system_get_capabilities` — machine-readable server capabilities for agent planning
- **MCP client configs**: Claude Code CLI, VS Code, Windsurf, openCxxW setup examples added to README

### Fixed

- Update notifier package names corrected (`okx-trade-mcp`, `okx-trade-cli`)
- CLI typecheck errors resolved (strict `parseArgs` types, `smol-toml` interop)

### Changed

- Total tools: 28 → 43

---

## [1.0.1] - 2026-02-28

### Added

- **Trailing stop order** (`swap_place_move_stop_order`) for SWAP — available in both CLI and MCP server
- **Update notifier** — on startup, prints a notice to stderr when a newer npm version is available

---

## [1.0.0] - 2026-02-28

### Added

- **MCP server** (`okx-trade-mcp`): OKX REST API v5 integration via the Model Context Protocol
- **CLI** (`okx-trade-cli`): command-line trading interface for OKX
- **Modules**:
  - `market` — ticker, orderbook, candles (no credentials required)
  - `spot` — place/cancel/amend orders, algo orders (conditional, OCO), fills, order history
  - `swap` — perpetual order management, positions, leverage, fills, algo orders
  - `account` — balance query, fund transfer
- **Algo orders**: conditional (take-profit / stop-loss) and OCO order pairs for spot and swap
- **CLI flags**: `--modules`, `--read-only`, `--demo`
- **Rate limiter**: client-side token bucket per tool
- **Config**: TOML profile system at `~/.okx/config.toml`
- **Error hierarchy**: `ConfigError`, `ValidationError`, `AuthenticationError`, `RateLimitError`, `OkxApiError`, `NetworkError` with structured MCP error payloads