desic-okx-agent 0.2.1 → 0.3.1

package/skills/okx-strategy-research/references/field-traps.md

@@ -0,0 +1,142 @@
+# Field traps
+
+These are the mistakes that actually get made. Each one is rejected by the source
+policy or the engine, so getting it right the first time saves a round trip.
+
+## Never probe for a field name
+
+```python
+# Rejected: getattr is unavailable to a strategy.
+price = getattr(ctx.bar, "close", None)
+
+# Correct.
+price = ctx.bar.close
+```
+
+Probing hides a protocol mismatch that should fail loudly. If a field does not
+exist, the run should stop and say so, not silently fall back to a default and
+produce plausible-looking nonsense.
+
+The same applies to `setattr`, `dir`, `vars`, `globals`, `locals`, `eval`, `exec`,
+`compile`, `__import__`, `open`, `input`, and any `__dunder__` access.
+
+## `position` is a method with two arguments
+
+```python
+# Wrong: not a property.
+if ctx.portfolio.position:
+
+# Wrong: side is required.
+ctx.portfolio.position(ctx.instrument_id)
+
+# Correct.
+if ctx.portfolio.position(ctx.instrument_id, "long") is not None:
+```
+
+## The size field is `quantity`
+
+Not `contracts`, `size`, `contractCount`, or `qty`.
+
+```python
+position = ctx.portfolio.position(ctx.instrument_id, "long")
+if position is not None:
+    held = position.quantity
+```
+
+## Decisions carry no size
+
+```python
+# Wrong: no quantity argument exists.
+ctx.open_long(2.0, "momentum")
+
+# Correct: reason first, host decides size.
+ctx.open_long("momentum")
+```
+
+## A limit price is never positional
+
+```python
+# Wrong: this function does not exist.
+ctx.open_long_limit("entry", 67000.0)
+
+# Wrong: the second positional argument is protection.
+ctx.open_long("entry", 67000.0)
+
+# Correct.
+ctx.open_long("entry", execution=ctx.limit_order(67000.0))
+```
+
+## Indicators return None during warm-up
+
+```python
+fast = ctx.indicators.ema(ctx.instrument_id, "1m", 20)
+slow = ctx.indicators.ema(ctx.instrument_id, "1m", 60)
+
+# Wrong: comparing None raises.
+if fast > slow:
+
+# Correct.
+if fast is None or slow is None:
+    return ctx.no_action("indicators warming up")
+if fast > slow:
+    ...
+```
+
+EMA needs `period` bars; ATR needs `period + 1`.
+
+## Indicators only accept `1m`
+
+```python
+# Rejected: a higher-timeframe bucket can be revised before it confirms.
+ctx.indicators.ema(ctx.instrument_id, "15m", 20)
+```
+
+Compute a higher-timeframe value from `ctx.market.bars(..., "15m", ...)` yourself,
+or use a `1m` period covering an equivalent span.
+
+## `ctx` is read-only
+
+```python
+# Rejected.
+ctx.as_of_ms = 0
+```
+
+## Return exactly one decision
+
+Every path through `on_bar` must return a decision object. Returning `None`, a
+string, or a bare number is rejected. Returning two actions from one bar is not
+expressible — emit one and act on the next bar.
+
+## Reversal must be explicit
+
+```python
+# Rejected while a long is open.
+return ctx.open_short("flip")
+
+# Correct: close first, reverse on a later bar.
+if ctx.portfolio.position(ctx.instrument_id, "long") is not None:
+    return ctx.close_long("exiting before reversing")
+```
+
+## `cancel_order` needs a live id
+
+```python
+orders = ctx.portfolio.open_orders
+if orders:
+    return ctx.cancel_order(orders[0].id, "no longer wanted")
+```
+
+An id that is not currently open is an error, not a no-op.
+
+## The current bar is the last item
+
+```python
+bars = ctx.market.bars(ctx.instrument_id, "1m", lookback=60)
+
+# Includes the bar that just closed — a "prior range high" computed this way
+# is contaminated by the current bar.
+highest = max(bar.high for bar in bars)
+
+# Correct: exclude the current bar.
+highest = max(bar.high for bar in bars[:-1])
+```

package/skills/okx-strategy-research/references/python-api.md

@@ -0,0 +1,125 @@
+# Strategy API
+
+Every object is immutable and bounded by `ctx.as_of_ms`. Field names are exactly
+as written here.
+
+## Handlers
+
+```python
+def on_bar(ctx):     # required, runs after each confirmed 1m close
+    ...
+
+def on_start(ctx):   # optional, initialization only, must return ctx.no_action(...)
+    ...
+```
+
+Both are synchronous and take exactly one positional argument. Ordinary helper
+functions may be defined freely; the host never calls them.
+
+## Context
+
+| Field | Meaning |
+| --- | --- |
+| `ctx.as_of_ms` | Cutoff in Unix milliseconds. During `on_bar`, the active bar's `closeTimeMs`. |
+| `ctx.instrument_id` | Active instrument, for example `BTC-USDT-SWAP`. |
+| `ctx.interval` | Event interval. Always `1m`. |
+| `ctx.kind` | `start` or `bar`. |
+| `ctx.bar` | The bar that just closed. Populated only during `on_bar`. |
+| `ctx.params` | Immutable mapping of saved parameters. `ctx.params.get("fastPeriod", 20)`. |
+
+## Market data
+
+```python
+bars = ctx.market.bars(ctx.instrument_id, "1m", lookback=240)
+```
+
+`lookback` returns the final N items and must be a positive integer. Supported
+intervals are `1m`, `3m`, `5m`, `15m`, `30m`, `1H`, `2H`, `4H`, `6H`, `12H`, and
+`1D`, but a higher timeframe must be requested for the run before it is readable.
+
+Always pass `lookback` when only a tail is needed. It costs the size of the window
+asked for, whereas omitting it copies every bar seen so far on every call — on a
+long run that is the difference between a few seconds and a few minutes.
+
+`Bar` fields: `openTimeMs`, `closeTimeMs`, `open`, `high`, `low`, `close`,
+`volume`, `confirmed`.
+
+All `1m` bars are confirmed. For higher intervals only the final item can be
+`confirmed=False`; its OHLCV contains solely the minutes already known. Require
+`bar.confirmed` before treating a higher-timeframe value as a confirmation.
+
+## Indicators
+
+```python
+fast = ctx.indicators.ema(ctx.instrument_id, "1m", 20)
+atr = ctx.indicators.atr(ctx.instrument_id, "1m", 14, offset=1)
+```
+
+Both accept only `"1m"`. `offset=0` is the current bar, `offset=1` the previous
+one. EMA returns `None` until `period` bars exist; ATR until `period + 1`, because
+true range needs a prior close. Always handle `None` explicitly.
+
+## Portfolio
+
+```python
+position = ctx.portfolio.position(ctx.instrument_id, "long")   # Position or None
+```
+
+`position(instrument_id, side)` is a **method** taking both arguments, not a
+property. `side` is `"long"` or `"short"`. `ctx.position(...)` is an alias.
+
+| Accessor | Meaning |
+| --- | --- |
+| `ctx.portfolio.cash_usdt`, `equity_usdt` | Virtual cash and account equity. |
+| `ctx.portfolio.used_margin_usdt`, `available_margin_usdt` | Virtual margin. |
+| `ctx.portfolio.positions` | Tuple of open positions. |
+| `ctx.portfolio.positions_for(instrument_id)` | Positions for one instrument. |
+| `ctx.portfolio.open_orders` | Resting limit orders. |
+| `ctx.portfolio.recent_fills`, `trades` | Simulated fills and closed trades. |
+
+`Position`: `instrumentId`, `side`, `quantity`, `averageEntryPrice`, `markPrice`,
+`contractValue`, `notionalUsdt`, `usedMarginUsdt`, `leverage`,
+`marginSafetyMultiplier`, `unrealizedPnlUsdt`, `entryFeeUsdt`, `stopLossPrice`,
+`takeProfitPrice`, `openedAtMs`, `updatedAtMs`.
+
+The size field is `quantity` — never `contracts`, `size`, or `contractCount`.
+
+`OpenOrder`: `id`, `instrumentId`, `action`, `quantity`, `filledQuantity`,
+`status`, `price`, `createdAtMs`.
+
+`Trade`: `id`, `instrumentId`, `side`, `quantity`, `entryPrice`, `exitPrice`,
+`usedMarginUsdt`, `leverage`, `realizedPnlUsdt`, `feesUsdt`, `openedAtMs`,
+`closedAtMs`.
+
+## Decisions
+
+Return exactly one per bar:
+
+```python
+ctx.no_action(reason)
+ctx.open_long(reason, protection=None, execution=None)
+ctx.open_short(reason, protection=None, execution=None)
+ctx.close_long(reason, execution=None)
+ctx.close_short(reason, execution=None)
+ctx.cancel_order(order_id, reason)
+```
+
+`reason` is required and is the first positional argument. Every other argument
+must be passed by keyword.
+
+Opening and closing decisions carry **no size**. The host derives a legal
+contract count from its budget and the instrument's rules.
+
+`execution` defaults to `ctx.market_order()`. The only alternative is
+`ctx.limit_order(price)`. There is no `open_long_limit`.
+
+`protection` accompanies an opening decision only, as a mapping of absolute
+prices:
+
+```python
+ctx.open_long("breakout", protection={"stopLossPrice": 67000.0, "takeProfitPrice": 70000.0})
+```
+
+`cancel_order` must name an id currently in `ctx.portfolio.open_orders`.
+
+Reversal is explicit: close the current side before opening the opposite one.

package/skills/okx-strategy-research/references/tools-and-data.md

@@ -0,0 +1,192 @@
+# Tools and data
+
+## Data is one-minute only
+
+Only confirmed one-minute bars are stored. Every higher timeframe is derived from
+them at read time, which is why a backtest and a live evaluation can never
+disagree about where a bucket starts.
+
+There is no `bar` parameter on any data tool.
+
+## Tools
+
+| Tool | Use |
+| --- | --- |
+| `data_list_instruments` | Every instrument with local history and its covered range. |
+| `data_coverage` | One instrument's range, bar count, and gap list. |
+| `data_download` | Download or repair an exact range. |
+| `data_download_progress` | Progress of a running download, for a progress display. |
+| `strategy_settings` | Read the assumptions every backtest uses by default. |
+| `strategy_settings_update` | Change saved assumptions. Pass only the keys to change. |
+| `strategy_environment` | Whether Python is ready. |
+| `strategy_environment_setup` | Create the venv and install packages. Prefer telling the user to run the CLI. |
+| `strategy_validate_source` | Static policy check with line numbers. |
+| `strategy_run_backtest` | Queue a run, returns `runId` immediately. |
+| `strategy_run_optimize` | Queue a parameter search. Splits the window, ranks out of sample. |
+| `strategy_get_optimization` | Ranked candidates with training and validation metrics side by side. |
+| `strategy_get_run` | Status, progress, summary metrics. |
+| `strategy_list_runs` | Recent runs, newest first. |
+| `strategy_get_run_equity` | Paged equity curve. |
+| `strategy_get_run_trades` | Paged closed trades. |
+| `strategy_get_run_actions` | Paged decisions the strategy emitted. |
+| `strategy_compare_runs` | Two or more runs side by side, with the assumptions that differ and comparability warnings. |
+| `strategy_cancel_run` | Cancel a queued or running run. |
+| `strategy_delete_run` | Delete a run and its stored series. Confirm with the user first. |
+
+## Check coverage before backtesting
+
+```
+data_coverage { "instId": "BTC-USDT-SWAP" }
+```
+
+`missingCount` above zero means the range has holes. A backtest over a window
+containing one fails outright, so repair it first:
+
+```
+data_download { "instId": "BTC-USDT-SWAP", "days": 90 }
+data_download { "instId": "BTC-USDT-SWAP", "fromMs": 1767225600000, "toMs": 1782950400000 }
+```
+
+`exhaustedBefore` means OKX has no data earlier than that point. Requesting more
+history below it will not help; say so instead of retrying.
+
+## Assumptions
+
+Leverage, entry budget, fees, slippage, margin safety, preload bars, and
+close-at-end are saved settings, readable with `strategy_settings`. A backtest
+request may override any of them for one run.
+
+State them when reporting a result: a return figure means nothing without the
+leverage and costs that produced it, and two runs are comparable only when these
+match. Every completed run records what it used, returned as `assumptions` from
+`strategy_get_run`.
+
+## Backtest windows
+
+`fromMs`/`toMs` bound the **evaluation** range. `preloadBars` are loaded entirely
+*before* it, as warm-up context, and are excluded from every reported statistic.
+
+The evaluation end is always clamped to at least one hour behind now, because the
+most recent minutes are the ones an exchange is most likely to revise.
+
+Limits: 365 evaluation days, 600,000 total bars including preload, minimum 2
+preload bars.
+
+## Runs are asynchronous
+
+`strategy_run_backtest` returns `{ runId, status: "queued" }`. Poll
+`strategy_get_run` until `status` is `completed`, `failed`, or `cancelled`.
+`progressPct` and `etaMs` are populated while running.
+
+A returned call is not a finished run. Never report metrics without confirming
+`status` is `completed`.
+
+## Read details in pages
+
+`strategy_get_run` carries summary metrics only. Equity, trades, and actions are
+separate paged reads with `offset` and `limit`. A full curve is tens of thousands
+of points; fetch only what supports the point you are making.
+
+## Parameter search
+
+`strategy_run_optimize` takes a backtest request plus a `space` and a `budget`:
+
+```
+strategy_run_optimize {
+  "instId": "BTC-USDT-SWAP",
+  "source": "...",
+  "params": { "fastPeriod": 20, "slowPeriod": 60 },
+  "space": {
+    "fastPeriod": { "min": 5,  "max": 50,  "step": 5 },
+    "slowPeriod": { "min": 20, "max": 200, "step": 10 }
+  },
+  "budget": 100,
+  "days": 90
+}
+```
+
+Pass `params` with the strategy's own defaults. Every key in `space` is checked
+against them, and a range naming a parameter the strategy never reads is rejected
+— otherwise every candidate would behave identically and the winner would be
+noise.
+
+Limits: at most 5,000 combinations in the space and a budget of at most 1,000. A
+budget below the widest parameter's value count is refused, because covering every
+value would then be impossible.
+
+The window is split **70/30**. Candidates are searched over the first segment and
+**ranked by the second**, which they never saw. Both segments come from one bar
+load, so they cannot disagree about the underlying data.
+
+Read the result with `strategy_get_optimization`, which returns candidates in rank
+order with `train` and `validation` metrics on each, plus a `verdict`:
+
+| Verdict | Meaning |
+| --- | --- |
+| `holds` | Profitable on the held-back segment, keeping a fair share of the training result. |
+| `overfit` | Profitable while being chosen, unprofitable or badly decayed afterwards. |
+| `weak` | Unprofitable on the held-back segment either way. |
+| `failed` | The candidate errored; read its `error`. |
+
+`rankBasis` names the formula behind `rankScore`. It is `calmar` when the
+validation segment is long enough to annualize, `return_over_drawdown` when it is
+not, and `return` when no candidate drew down. Quote it — the column is not always
+the same quantity.
+
+## Reporting a search
+
+Quote the **validation** figures, not the training ones. The training numbers
+describe performance over the bars that selected the parameters, so they are not
+evidence and must never be presented as the result.
+
+Show both columns anyway. The gap between them is the finding: a large training
+return beside a weak validation return means the parameters fitted noise, and that
+is worth saying plainly rather than reporting the best row as a success.
+
+Say that the winner's validation figure is still optimistic. Ranking many
+candidates by that score selects for a high one, so the split removes most of the
+bias but not all of it, and the remainder grows with the budget. A clean estimate
+needs a period later than the whole search window. Never present the leader's
+validation return as an expected future return.
+
+Prefer a candidate whose neighbours also hold over a single sharp optimum. A lone
+spike surrounded by poor results is a coincidence in the data, not a setting.
+
+To use a winning set, write it to `<strategy>.params.json` beside the strategy —
+never edit the strategy source, which is the user's. Then run one ordinary
+backtest with those parameters to confirm, and say that this confirmation still
+covers the same period the search used.
+
+## Comparing runs
+
+```
+strategy_compare_runs { "runIds": ["bt_abc123", "bt_def456"] }
+```
+
+Two to six runs. The response carries each run's metrics, the assumption keys whose
+values differ, the ones every run shares, and a `warnings` array.
+
+**Read `warnings` before the metrics and repeat them to the user.** They are the
+reason a comparison may be meaningless:
+
+| Warning code | Meaning |
+| --- | --- |
+| data&#95;snapshot | The runs consumed different bars. Any difference may come from the data rather than the strategy. |
+| instrument | Different instruments. Each return reflects its own market's move. |
+| window | Different evaluation windows, so the totals span different amounts of time. |
+| assumptions | Different leverage, fees, slippage, or budget. |
+| incomplete | A run did not finish and has no metrics. |
+
+A comparison is only evidence that one variant beats another when every run shares
+one `dataSnapshotId`, one instrument, one window, and one set of costs. When it does
+not, say which of those differed instead of naming a winner.
+
+Equity curves are indexed to 100 at each run's own start, so different initial
+equity does not change the shape. Comparing absolute equity between runs that
+started from different balances says nothing.
+
+## Reproducibility
+
+Each run records a `dataSnapshotId` whose hash covers the exact bars consumed. Two
+identical requests over unchanged data yield the same id and the same metrics. A
+differing id means the underlying data changed — quote the id when comparing runs.

package/skills/okx-trading/SKILL.md

@@ -1,16 +1,17 @@
 ---
 name: okx-trading
-description: Precheck and execute direct OKX leverage, ordinary-order, algo-order, amend, cancel, and position-close operations. Use when the user explicitly requests an OKX trading action and has configured an API key with the required official permission.
+description: Precheck and execute direct OKX perpetual-swap leverage, ordinary-order, algo-order, amend, cancel, and position-close operations. Use when the user explicitly requests an OKX perpetual trading action and has configured an API key with the required official permission.
 ---
 
 # OKX Trading
 
-1. Identify the account alias, environment, instrument, side, margin mode, position side, order type, price, and size from the user's request. Do not invent missing trading intent.
-2. Call `market_get_instrument`; treat `size` as contracts for derivatives and respect `lotSz`, `minSz`, and `tickSz`.
-3. Call `market_get_decision_snapshot`. Do not proceed when `consistent` is false.
-4. Call `trade_evaluate_plan`, then `trade_precheck_order` for ordinary orders or `trade_precheck_algo_order` for strategy orders. Resolve every blocker before submitting.
-5. Create a stable, unique `executionKey` for each intended mutation. Reuse it only when retrying the exact same intent.
-6. Call the narrowest write tool that matches the request. Do not substitute batch cancellation or full position closure for a narrower action.
-7. If a result is `AMBIGUOUS_WRITE`, inspect remote order state. Never retry with a new execution key until the original outcome is resolved.
-8. Report the exchange environment, returned order identifiers, status, reconciliation state, and any warnings.
-9. Never use or propose withdrawal, transfer, deposit, or API-key-management operations.
+1. This workflow supports OKX perpetual swaps only. Require an `instId` ending in `-SWAP`; refuse spot, dated futures, options, and every other instrument type.
+2. Identify the account alias, instrument, side, margin mode, position side, order type, price, and size from the user's request. Use the account environment detected by the Runtime; do not ask the user to classify the API key or invent missing trading intent.
+3. Call `market_get_instrument`; treat `size` as contracts and respect `lotSz`, `minSz`, and `tickSz`.
+4. Call `market_get_decision_snapshot`. Do not proceed when `consistent` is false.
+5. Call `trade_evaluate_plan`, then `trade_precheck_order` for ordinary orders or `trade_precheck_algo_order` for strategy orders. Resolve every blocker before submitting.
+6. Create a stable, unique `executionKey` for each intended mutation. Reuse it only when retrying the exact same intent.
+7. Call the narrowest write tool that matches the request. Do not substitute batch cancellation or full position closure for a narrower action.
+8. If a result is `AMBIGUOUS_WRITE`, inspect remote order state. Never retry with a new execution key until the original outcome is resolved.
+9. Report the exchange environment, returned order identifiers, status, reconciliation state, and any warnings.
+10. Never use or propose withdrawal, transfer, deposit, or API-key-management operations.