desic-okx-agent 0.2.0 → 0.3.0

package/python/desic_strategy/timeframe.py

@@ -0,0 +1,150 @@
+"""One-minute to higher-timeframe aggregation.
+
+This mirrors the TypeScript `TimeframeAggregator` exactly. Both are verified
+against the same fixtures so a backtest and the terminal's own views can never
+disagree about a bucket boundary.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+ONE_MINUTE_MS = 60_000
+
+INTERVAL_MS: dict[str, int] = {
+    "1m": ONE_MINUTE_MS,
+    "3m": 3 * ONE_MINUTE_MS,
+    "5m": 5 * ONE_MINUTE_MS,
+    "15m": 15 * ONE_MINUTE_MS,
+    "30m": 30 * ONE_MINUTE_MS,
+    "1H": 60 * ONE_MINUTE_MS,
+    "2H": 120 * ONE_MINUTE_MS,
+    "4H": 240 * ONE_MINUTE_MS,
+    "6H": 360 * ONE_MINUTE_MS,
+    "12H": 720 * ONE_MINUTE_MS,
+    "1D": 1_440 * ONE_MINUTE_MS,
+}
+
+
+class DataContractError(Exception):
+    """Raised when input violates the one-minute data contract."""
+
+
+@dataclass(frozen=True)
+class Bar:
+    """An immutable OHLCV bar covering ``[open_time_ms, close_time_ms)``."""
+
+    open_time_ms: int
+    close_time_ms: int
+    open: float
+    high: float
+    low: float
+    close: float
+    volume: float
+    confirmed: bool = True
+
+    # Protocol field names are camel-case; expose both spellings so strategy
+    # code can use the documented names without a conversion step.
+    @property
+    def openTimeMs(self) -> int:  # noqa: N802 - protocol field name
+        return self.open_time_ms
+
+    @property
+    def closeTimeMs(self) -> int:  # noqa: N802 - protocol field name
+        return self.close_time_ms
+
+
+def interval_ms(interval: str) -> int:
+    if interval not in INTERVAL_MS:
+        supported = ", ".join(INTERVAL_MS)
+        raise DataContractError(f"Unsupported interval '{interval}'. Supported: {supported}")
+    return INTERVAL_MS[interval]
+
+
+class TimeframeAggregator:
+    """Incrementally folds a contiguous confirmed one-minute feed into one timeframe.
+
+    Two rules keep the output safe to hand to a strategy:
+
+    1. A leading partial bucket is discarded rather than published as a
+       completed candle, which would invent a bar that never existed.
+    2. Only the final item may be unconfirmed, and its OHLCV contains solely
+       the minutes already known at the current cutoff.
+    """
+
+    __slots__ = ("_completed", "_current", "_interval_ms", "_last_input_open", "_maximum", "_started")
+
+    def __init__(self, interval: str, maximum_bars: int = 20_000) -> None:
+        if maximum_bars <= 0:
+            raise DataContractError("maximum_bars must be greater than zero")
+        self._interval_ms = interval_ms(interval)
+        self._maximum = maximum_bars
+        self._completed: list[Bar] = []
+        self._current: Bar | None = None
+        self._started = False
+        self._last_input_open: int | None = None
+
+    def push(self, bar: Bar) -> None:
+        if bar.close_time_ms - bar.open_time_ms != ONE_MINUTE_MS:
+            raise DataContractError("Timeframe aggregation requires closed one-minute bars")
+        if self._last_input_open is not None:
+            if bar.open_time_ms == self._last_input_open:
+                raise DataContractError("Timeframe aggregation received a duplicate one-minute bar")
+            if bar.open_time_ms < self._last_input_open:
+                raise DataContractError("Timeframe aggregation received an out-of-order one-minute bar")
+            if bar.open_time_ms != self._last_input_open + ONE_MINUTE_MS:
+                raise DataContractError("Timeframe aggregation detected a missing one-minute bar")
+        self._last_input_open = bar.open_time_ms
+
+        step = self._interval_ms
+        bucket_open = (bar.open_time_ms // step) * step
+        bucket_close = bucket_open + step
+
+        if not self._started:
+            if bar.open_time_ms != bucket_open:
+                return
+            self._started = True
+
+        current = self._current
+        if current is not None and current.open_time_ms == bucket_open:
+            self._current = Bar(
+                open_time_ms=current.open_time_ms,
+                close_time_ms=current.close_time_ms,
+                open=current.open,
+                high=max(current.high, bar.high),
+                low=min(current.low, bar.low),
+                close=bar.close,
+                volume=current.volume + bar.volume,
+                confirmed=bar.close_time_ms == current.close_time_ms,
+            )
+            return
+
+        if current is not None:
+            self._completed.append(current)
+            while len(self._completed) > self._maximum:
+                self._completed.pop(0)
+        self._current = Bar(
+            open_time_ms=bucket_open,
+            close_time_ms=bucket_close,
+            open=bar.open,
+            high=bar.high,
+            low=bar.low,
+            close=bar.close,
+            volume=bar.volume,
+            confirmed=bar.close_time_ms == bucket_close,
+        )
+
+    def snapshot(self) -> tuple[Bar, ...]:
+        if self._current is None:
+            return tuple(self._completed)
+        return (*self._completed, self._current)
+
+    def latest(self) -> Bar | None:
+        return self._current
+
+
+def aggregate(bars: list[Bar], interval: str, maximum_bars: int = 20_000) -> tuple[Bar, ...]:
+    aggregator = TimeframeAggregator(interval, maximum_bars)
+    for bar in bars:
+        aggregator.push(bar)
+    return aggregator.snapshot()

package/python/main.py

@@ -0,0 +1,18 @@
+"""Isolated entry point for the strategy runner.
+
+The host invokes this as ``python3 -I -u main.py``. ``-I`` is deliberate: it
+ignores environment variables (including ``PYTHONPATH``) and the user site
+directory, so a run cannot be redirected by ambient configuration. Because
+``-I`` also implies ``-P``, the script's own directory is *not* on ``sys.path``,
+so this file adds it explicitly — that is the package root and nothing else.
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from desic_strategy.runner import main  # noqa: E402 - import needs the path above
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/okx-live-trading/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: okx-live-trading
+description: Run a backtested Python strategy against a real OKX account. Use for creating and starting live profiles, reading what they decided, diagnosing why an order was refused, and stopping a profile.
+---
+
+# OKX Live Trading
+
+A live profile binds one strategy, one instrument, one account, and a set of risk budgets. Once
+enabled it acts on every closed one-minute bar without being asked again.
+
+Read `references/lifecycle.md` before creating or starting anything.
+
+**This spends real money.** Every constraint below exists because of a specific way money gets
+lost, not as ceremony.
+
+## Ask before committing real money
+
+On the **demo** environment, work independently: write, backtest, tune, create a profile, start it,
+read the signals, stop it. That is a complete verification loop and you should use all of it without
+checking in at each step.
+
+Before enabling any profile whose `environment` is **`live`**, stop and ask the operator. Nothing in
+the system will stop you, so this is your responsibility rather than a check you will run into.
+
+State these things and wait for an explicit yes:
+
+- which profile, on which instrument and account
+- the entry budget, side budget, and daily loss limit, in USDT
+- the backtest behind it, quoting **validation-segment** figures rather than training ones
+- what the demo run showed: how many signals, how many were refused and by which gate
+- that starting it commits real money to a strategy that will act without further approval
+
+"Should I start it?" on its own is not asking. The operator needs the numbers in front of them to
+answer usefully.
+
+If they say yes, start it and report what happened. If they do not answer, leave it stopped — a
+profile nobody approved should not be trading.
+
+If `live_create_profile` and `live_start` are absent from your tool list, the operator has not
+enabled agent access. Say so and stop; do not reach for `trade_place_order` to do the same thing by
+hand.
+
+## Workflow
+
+1. Establish the strategy first, through `okx-strategy-research`: write it, validate it, backtest
+   it, and tune it. A profile cannot be enabled until its exact source has completed a backtest on
+   its exact instrument, so this is not optional.
+2. Confirm the market data environment matches the profile you intend to create. Demo and live are
+   separate markets with different prices; `desic-okx market env` reports which is streaming, and a
+   mismatch is refused at enable time.
+3. Choose budgets deliberately and be able to defend each one. `live_create_profile` requires a
+   `rationale` from you: which backtest justified this, and why these numbers. Write it for someone
+   reviewing the profile a month later.
+4. Call `live_readiness` before `live_start`. It lists everything outstanding at once, so you fix
+   the set rather than discovering one blocker at a time.
+5. Start on demo. Let it run long enough to produce several signals of more than one kind.
+6. Read `live_signals` and report what actually happened, including the refusals.
+7. Stop with `live_stop` when the observation is done. Never leave a profile running because it
+   might be useful later.
+
+## Choosing budgets
+
+These are the numbers every risk gate measures against, so vague choices produce a profile that
+either refuses everything or risks more than intended.
+
+- `entryBudgetUsdt` is margin committed per entry, not notional. At 10x leverage, 100 USDT of
+  margin is roughly 1,000 USDT of exposure. Pick an amount the operator could lose entirely
+  without it mattering.
+- `sideBudgetUsdt` must be at least `entryBudgetUsdt`, or no entry can ever be placed. Two to four
+  times is a reasonable starting point.
+- `dailyLossLimitUsdt` is the only stop-like constraint in the system. Set it small on a first
+  run — one or two times the entry budget — so it is easy to trigger and you find out whether it
+  works before relying on it.
+- `cooldownSeconds` bounds how often a misbehaving strategy can trade. Zero is appropriate only
+  once you have seen the signal history and know the frequency is intended.
+
+Restricting to one direction with `allowShort: false` removes half the ways a first run can
+surprise someone. Prefer it unless the strategy genuinely needs both.
+
+`leverage` is not only a local number. Starting a profile writes it to the exchange for that
+instrument and margin mode, and refuses to start if the write fails — the entry budget is sized
+against it, so a mismatch means the margin actually committed differs from the budget by that
+ratio. Mention this when the operator's account trades that instrument by hand as well: the setting
+is shared, so their manual positions will be on the profile's leverage afterwards.
+
+## Reading results
+
+State facts before interpretation: which profile, which minutes, and the counts by status.
+
+**Report refusals, not only fills.** A `blocked` signal is risk control working, and the gate that
+produced it is recorded. A day with no orders and a loop that silently stopped evaluating look
+identical unless you say which one happened.
+
+Never describe a live result as expected future return. A handful of minutes is not evidence of
+anything, and neither is a profitable afternoon.
+
+## When something is wrong
+
+- **`ambiguous`** means an order may or may not exist at the exchange. Nothing is retried
+  automatically, and you must not retry it either. Read the order with `account_get_order` and the
+  position with `account_get_positions`, report what you found, and let a person decide.
+- **A profile that stopped itself** hit three consecutive systemic failures. Read `lastError`,
+  explain the cause, and fix that before suggesting it be restarted.
+- **Repeated `blocked` on one gate** is usually a configuration mismatch rather than a fault —
+  a side budget below the entry budget, or a daily loss limit already reached. Say which.
+
+## Constraints
+
+- One profile per account, environment, and instrument.
+- A profile trades the strategy source captured when it was created. Editing the file changes
+  nothing; a new version needs a new backtest and a new profile.
+- Closing actions are sized from the open position and skip the budget, loss, and cooldown gates.
+  A limit that prevented closing a losing position would make the loss worse.
+- Reversal is not supported. Close before opening the opposite side.
+- `set_protection` and `cancel_protection` do not exist here. Attach take-profit and stop-loss at
+  entry or not at all.
+- Stopping is always permitted and never checked. When in doubt, stop.

package/skills/okx-live-trading/agents/openai.yaml

@@ -0,0 +1,9 @@
+interface:
+  display_name: "OKX Live Trading"
+  short_description: "Run a backtested strategy against a real account, with risk gates and signal history."
+  default_prompt: "Use $okx-live-trading to review what my live profiles decided today."
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "desic-okx"
+      description: "Desic OKX Agent MCP server"

package/skills/okx-live-trading/references/lifecycle.md

@@ -0,0 +1,128 @@
+# Live profile lifecycle
+
+## Tools
+
+| Tool | Use |
+| --- | --- |
+| `live_list_profiles` | Every profile with its state and error streak. |
+| `live_get_profile` | One profile, including its rationale and the backtest behind it. |
+| `live_readiness` | Everything outstanding before it can start, all at once. |
+| `live_signals` | What it decided per minute, including every refusal. |
+| `live_stop` | Disable. Always permitted. |
+| `live_create_profile` | Create one. Present only when the operator enabled agent access. |
+| `live_start` | Enable one. Same condition. Ask first when the environment is `live`. |
+| `live_delete_profile` | Remove a stopped profile and its signal history. Refused while enabled. |
+
+Creating a profile never starts it. Enabling is the only step that can lead to an order.
+
+Deleting removes the signal history along with the profile, which is the record of what it did.
+Prefer stopping and leaving it in place; delete only when asked, and never as cleanup after an
+experiment worth reviewing.
+
+## Creating
+
+```
+live_create_profile {
+  "name": "ema-btc-demo",
+  "source": "...",
+  "instId": "BTC-USDT-SWAP",
+  "account": "demo",
+  "environment": "demo",
+  "leverage": 10,
+  "entryBudgetUsdt": 100,
+  "sideBudgetUsdt": 400,
+  "dailyLossLimitUsdt": 200,
+  "cooldownSeconds": 300,
+  "allowShort": false,
+  "origin": "agent",
+  "rationale": "bt_a1b2 validation segment +8.2% with 4.1% max drawdown over 30 days; entry budget is 0.5% of account equity; short disabled because the strategy only defines a long entry"
+}
+```
+
+Set `origin: "agent"` and supply a `rationale` whenever you create a profile. It is required, and
+it is what makes the profile reviewable later — write which run justified it and why each budget
+was chosen, not a restatement of the parameters.
+
+## Preconditions
+
+`live_readiness` returns every unmet one together. There are six.
+
+| Code | Meaning |
+| --- | --- |
+| no_backtest | The exact source has not completed a backtest on this instrument. |
+| python_missing | The local Python environment is not ready. |
+| account_unverified | OKX did not accept the credentials. |
+| no_trade_permission | The API key cannot trade. |
+| contract_unreadable | No usable contract specification, so no size can be derived. |
+| environment_mismatch | The profile's venue differs from the streaming market data. |
+
+The backtest is matched by **source hash**, so changing one character means it no longer counts.
+A losing backtest satisfies this: the requirement is that one ran and someone saw the behaviour,
+not that it made money. Do not tune a strategy further in order to satisfy this check — that
+inverts what it is for.
+
+Every precondition is a verifiable fact about the system, so readiness returning empty means the
+profile *can* start — not that it *should*. Whether to commit real money is the operator's decision,
+and on a `live` profile you ask first. See the asking rules in `SKILL.md`.
+
+## The risk gates
+
+Checked in order on every closed minute, cheapest first. **Every gate refuses; none adjusts.** An
+intent needing more than the budget allows is rejected and recorded, never quietly resized — so a
+fill is never an order whose size was rewritten.
+
+| # | Gate | Refuses when |
+| --- | --- | --- |
+| 1 | disabled | The profile is no longer enabled. |
+| 2 | generation | It was stopped while the strategy was deciding. |
+| 3 | direction | The profile forbids opening that side. |
+| 4 | entry_budget | No margin available for one entry. |
+| 5 | side_budget | That direction is already fully committed. |
+| 6 | daily_loss | The UTC day's realized loss reached the limit. |
+| 7 | cooldown | Not enough time since the last order was actually sent. |
+| 8 | minimum_size | The budget cannot buy one legal contract lot. |
+
+Closing actions are sized from the open position and skip gates 4 through 7. A loss limit that
+blocked closing a losing position would deepen the loss, and a budget-sized partial close would
+leave exposure the strategy believed it had removed.
+
+Position, committed margin, and the day's realized loss all come from the exchange, never from a
+local tally — a manual close or a partial fill would leave a local figure wrong.
+
+## Signal states
+
+| Status | Meaning |
+| --- | --- |
+| no_action | The strategy asked for nothing. |
+| submitted | An order reached the exchange. |
+| blocked | A gate refused; the gate is recorded. |
+| error | Evaluation failed. |
+| ambiguous | The outcome is unknown. Needs a person. |
+| reserved | Claimed but never decided — a crash remnant. |
+
+One signal per closed minute, guaranteed by a unique constraint. Redelivered bars, coalesced
+bursts, and restarts all converge on at most one order per minute.
+
+## Recovery
+
+At startup, profiles a dead worker left running are stopped and their unresolved signals are
+checked against the exchange. Nothing is ever resubmitted: re-sending an order that may already
+exist is worse than missing one.
+
+"The exchange says there is no such order" closes a signal. "The exchange could not be reached"
+does not — that becomes `ambiguous`, because treating it as absence would discard an order that
+may have filled. A still-open order also becomes `ambiguous` rather than being closed
+automatically, since that would decide for someone what to do with exposure they have not seen.
+
+## Automatic shutdown
+
+Three consecutive **systemic** failures stop a profile. Systemic means it will not fix itself: a
+missing interpreter, invalid source, revoked permission, a strategy raising, an ambiguous write, or
+anything unrecognised. A dropped connection or a rate limit is transient — recorded, but it does
+not count, and twenty in a row leave the profile running.
+
+A success clears the streak. A transient failure between two systemic ones does not, because the
+fault is still there.
+
+When you find a stopped profile, read `lastError` and explain the cause rather than suggesting a
+restart. Restarting into the same fault produces the same three failures.

package/skills/okx-strategy-research/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: okx-strategy-research
+description: Write, validate, and backtest Python trading strategies against local OKX one-minute history. Use for strategy authoring, backtest execution, reading backtest results, and diagnosing local data coverage or gaps.
+---
+
+# OKX Strategy Research
+
+Strategies are Python modules that define `on_bar(ctx)`. The host owns the clock,
+the market window, matching, sizing, and risk. A strategy returns one decision
+per bar and never receives an exchange client, credentials, or an order API.
+
+Read `references/python-api.md` before writing code. Use the documented field
+names directly; do not probe for spellings.
+
+## Workflow
+
+1. Confirm the environment once with `strategy_environment`. If it is not ready,
+   tell the user to run `desic-okx strategy env --setup` rather than attempting
+   installation yourself.
+2. Write the strategy. Return exactly one decision per bar. Do not pass a
+   contract count — the host derives size from its own budget.
+3. Call `strategy_validate_source` before every backtest. It returns violations
+   with line numbers in milliseconds, so it is always cheaper than discovering a
+   forbidden import after queuing.
+4. Check coverage with `data_coverage` for the instrument and range you intend to
+   test. Repair gaps with `data_download` first: a backtest over a window with a
+   hole fails closed rather than skipping the minute.
+5. Queue the run with `strategy_run_backtest`. It returns a `runId` immediately.
+   Poll `strategy_get_run` until `status` is `completed`, `failed`, or
+   `cancelled`. Never assume a run finished because the call returned.
+6. Read details only as needed, through `strategy_get_run_equity`,
+   `strategy_get_run_trades`, and `strategy_get_run_actions`. Request pages; a
+   full equity curve is tens of thousands of points.
+7. To tune parameters, use `strategy_run_optimize` rather than running backtests
+   in a loop and picking the best. It splits the window and ranks on a segment the
+   candidates never saw; choosing by hand across whole-window results selects for
+   overfitting with no way to detect it. Read `references/tools-and-data.md`
+   before reporting a search.
+8. To weigh two runs against each other, use `strategy_compare_runs` rather than
+   quoting two reports in sequence. Read its `warnings` first and repeat them: two
+   runs over different data, instruments, windows, or costs are not two answers to
+   one question, and that is invisible in the metrics alone.
+
+## Where this leads
+
+Research is one segment of a longer chain: market analysis produces an idea, this
+skill turns it into a strategy with evidence, and `okx-live-trading` binds it to an
+account. A backtest here is the hard precondition for enabling a live profile, so
+what you do at this stage is what a live profile will later be justified by.
+
+Two things follow from that:
+
+- A backtest is matched to a profile by **source hash**, not filename. Editing the
+  strategy after a good run invalidates that evidence, and the profile will refuse
+  to enable until it is rerun.
+- Demo and live are separate markets with different prices. A run on demo bars does
+  not justify a live profile; that window has to be rerun against live data.
+
+If `live_*` tools are absent from your list, the operator has not enabled agent
+access to live trading. Finish the research and say what the next step would be
+rather than reaching for `trade_place_order` to trade the strategy manually.
+
+## Reporting results
+
+State the facts before any interpretation: instrument, evaluation range, bar
+count, `dataSnapshotId`, trade count, and the cost assumptions used.
+
+Then report `returnPct`, `maxDrawdownPct`, `calmar`, `winRatePct`,
+`profitFactor`, `totalFeesUsdt`, and `exposurePct`. Win rate and profit factor
+are net of fees.
+
+Always say explicitly that a backtest is a simulation. Name the specific
+assumptions that make it one: fees, slippage, fills at the next bar's open, and
+a conservative K-line estimate for limit orders with no order-book queue. Never
+describe a backtest result as expected future return.
+
+When `marginExhausted` is true, say the run hit its simulated collateral limit
+and that this is a research risk boundary, not an OKX liquidation estimate.
+
+## Judging a result
+
+A high trade count with a profit factor near or below 1 usually means fees
+dominate the edge; check `totalFeesUsdt` against the equity change before
+concluding the logic is wrong.
+
+Treat a single strong result on one range with suspicion. Prefer parameters that
+stay reasonable across neighbouring values over a single sharp optimum, and say
+so when a result looks like it was selected rather than discovered.
+
+After a parameter search, quote the validation metrics and never the training
+ones. Report both columns so the gap is visible, and call a candidate overfitted
+when the search does. Add that the winner's validation figure is still optimistic,
+because it was selected by that very score.
+
+A verdict of `unexplained` — losing on training, winning on validation — is not a
+better `holds`. Nothing crossed the split, so the validation profit describes those
+particular bars rather than the parameters. When most of the table reads
+`unexplained`, say that the window is the problem: the validation segment favoured
+this kind of strategy, and the search cannot distinguish between the candidates.
+Propose a window containing rises, falls, and chop rather than reporting a winner.
+
+Report a negative result plainly. A strategy that loses money is a valid finding.
+
+## Constraints
+
+- Imports are limited to `collections`, `dataclasses`, `math`, `numpy`,
+  `pandas`, `statistics`, and `typing`.
+- `getattr`, `setattr`, `eval`, `exec`, `open`, `__import__`, dunder access,
+  async handlers, and generators are rejected. Read documented fields directly.
+- Only `1m` bars are stored. Every higher timeframe is derived from them.
+- Indicators accept only `1m`, because a higher-timeframe bucket can still be
+  revised before it confirms.
+- A strategy cannot see past its cutoff. Do not write code that tries.

package/skills/okx-strategy-research/agents/openai.yaml

@@ -0,0 +1,9 @@
+interface:
+  display_name: "OKX Strategy Research"
+  short_description: "Write, validate, and backtest Python strategies on local OKX history."
+  default_prompt: "Use $okx-strategy-research to backtest an EMA trend strategy on BTC-USDT-SWAP."
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "desic-okx"
+      description: "Desic OKX Agent MCP server"

package/skills/okx-strategy-research/references/execution-semantics.md

@@ -0,0 +1,107 @@
+# Execution semantics
+
+Understanding when a decision becomes a fill is the difference between a backtest
+that means something and one that quietly reports impossible performance.
+
+## The clock
+
+`on_bar` runs after a one-minute bar has **closed and confirmed**. The decision
+is made at that close. A market decision fills at the **following bar's open**,
+never at the close the decision was made on.
+
+```
+bar[k] closes ──▶ on_bar sees bar[k] ──▶ decision ──▶ fills at bar[k+1].open
+```
+
+This one-bar delay is why `preloadBars` must be at least 2: an action needs a
+following open to fill at.
+
+## Limit orders
+
+A limit decision becomes a resting order at the next bar's open, then waits.
+
+Matching is deliberately conservative:
+
+- A buy requires a later bar to trade **strictly below** its limit. Touching the
+  limit exactly is not a fill.
+- A sell requires a bar to trade **strictly above** its limit.
+- Any single bar can absorb at most **10% of that bar's volume**.
+
+There is no historical order book, so there is no queue position, no latency
+model, and no guarantee a real venue would have filled the same order. Treat a
+limit fill as an estimate, never a promise.
+
+Resting orders appear in `ctx.portfolio.open_orders`, can fill partially, and can
+be cancelled with `ctx.cancel_order(order_id, reason)`.
+
+## Protection
+
+`protection` on an opening decision is a request carrying absolute prices. The
+simulator checks it against each following bar's OHLC.
+
+When a single bar spans both the stop and the target, the **stop is taken**.
+Intrabar ordering is unknowable from OHLC alone, so the adverse outcome is
+assumed rather than the favourable one.
+
+A full close removes attached protection automatically.
+
+## Sizing and margin
+
+The strategy never specifies size. The host computes a contract count from the
+entry budget, leverage, and the instrument's own contract specification, then
+aligns it down to a legal lot.
+
+The specification is read from OKX per instrument: `ctVal` and `ctMult` give the
+base-currency units one contract represents, and `lotSz` / `minSz` decide which
+quantities are legal. These differ between instruments — BTC-USDT-SWAP is 0.01
+BTC per contract with a 0.1 lot, while ETH-USDT-SWAP is 0.1 ETH with a 0.01 lot
+— so the same budget buys different contract counts. A run whose specification
+cannot be read fails rather than assuming one, because a guessed contract size
+produces confident metrics for positions that could never have been taken.
+
+Opening reserves `notional / leverage * marginSafetyMultiplier` from equity. If an
+adverse move exhausts that collateral, the position is closed at the conservative
+available price and `marginExhausted` is set.
+
+That is a **research risk boundary, not an OKX liquidation model**. Real
+liquidation depends on maintenance margin tiers, funding, and mark price
+mechanics that this simulation does not reproduce.
+
+## Costs
+
+Fees and slippage apply to every fill. Defaults are 5 bps taker, 2 bps maker, and
+1 bp slippage on entry and exit.
+
+Fees compound quickly on a high-turnover strategy. A profit factor near 1 with
+hundreds of trades usually means fees consumed the edge — compare
+`totalFeesUsdt` against the change in equity before concluding the signal is
+wrong.
+
+## Multi-timeframe
+
+`on_bar` fires on every confirmed minute regardless of which timeframes the
+strategy reads. Reading `30m` bars changes the data, not the callback clock.
+
+To act only on a 30-minute close:
+
+```python
+buckets = ctx.market.bars(ctx.instrument_id, "30m", lookback=2)
+if not buckets[-1].confirmed:
+    return ctx.no_action("waiting for the 30m close")
+```
+
+The resulting decision still fills at the next one-minute open.
+
+Do not inspect a higher-timeframe bar's high or low and emit a delayed close to
+imitate a protective fill. Use `protection` so the simulator monitors it against
+each minute.
+
+## What cannot happen
+
+`ctx.market.bars(...)` returns only bars at or before `ctx.as_of_ms`. The window
+ends exactly at the cutoff, so there is no way to read a later bar — attempting
+it simply yields the same visible window.
+
+A window with a missing minute fails the run outright rather than skipping it,
+because performance measured over a timeline that never existed is worse than no
+answer.