perkbridge-connect 1.0.0b1__tar.gz

perkbridge_connect-1.0.0b1/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+perkbridge.properties
+.perkbridge/

perkbridge_connect-1.0.0b1/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 1.0.0b1 (unreleased)
+
+First beta.
+
+- `Config`: properties file, `[strategy.<name>]` sections, environment and `_FILE` secrets, and validation that reports every problem at once.
+- `Connect`: reads, orders, modifies, cancels and closes. Includes the idempotency journal with recovery on restart, refused/rejected/unknown outcomes, the local envelope, and retries with `Retry-After`.
+- `Strategy`, `run`, `run_once`: interval, at, cron and manual schedules with time zones and daylight saving time, market hours, the event feed with a saved cursor, and persisted `ctx.state`.
+- Time Machine: replays a past window with a local fill simulator. Nothing is sent.
+- `perkbridge-run` command line.
+- Review fixes, trading safety:
+  - The same intent after an ambiguous answer reuses its key.
+  - The one-in-flight rule holds after a wait timeout and after a restart.
+  - `close_all` stops at an ambiguous close.
+  - `then_stops` is journaled and applied once after a late fill.
+  - `then_stops` counts as set only when the modify is `done`.
+  - Refused or failed stop modifies are retried with backoff, then reported.
+  - The same key with different `then_stops` is refused.
+  - `pending_stops()` lists stops that are not set yet.
+  - `stops_status()` and `stops_needing_attention()` keep failed stop
+    protection visible until the position closes.
+  - The local envelope is checked inside the submission lock, after the
+    same-key replay check.
+  - An abandoned or aged unanswered key is never sent late.
+  - Derived keys use a digest of the whole key.
+  - A stops watcher thread (`order.stops_watch_s`) sets delayed-fill stops
+    with no further calls.
+  - `StopsNotSet` carries the placed order; a same-intent retry never opens
+    a second position.
+  - The watcher's exit is serialized with its start.
+  - Pruning keeps unresolved stop intents and orders that are not final.

perkbridge_connect-1.0.0b1/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

perkbridge_connect-1.0.0b1/PKG-INFO

@@ -0,0 +1,348 @@
+Metadata-Version: 2.5
+Name: perkbridge-connect
+Version: 1.0.0b1
+Summary: Python client for the PerkBridge Connect Trading API: idempotent orders, strategies on a schedule, events.
+Project-URL: Homepage, https://perkbridge.eu
+Project-URL: Source, https://github.com/perkbridge/connect-python-client
+Author: PerkBridge
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: api-client,metatrader,mt5,perkbridge,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: tzdata; sys_platform == 'win32'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml>=6; extra == 'dev'
+Requires-Dist: ruff==0.17.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# perkbridge-connect
+
+The Python library for the PerkBridge Connect Trading API (`/v1/trading`).
+Write a strategy as a small class, keep the connection in a properties file,
+and run it. The library takes care of authentication, idempotency, duplicate
+prevention, scheduling, reconnects, events and errors.
+
+Status: **1.0.0b1, beta.** It has been tested against a real Control Plane with
+simulator accounts. It has not yet been run against a real MT5 terminal.
+Use demo accounts.
+
+```
+pip install perkbridge-connect      # once published; import name: perkbridge
+```
+
+Python 3.10 to 3.13. The only runtime dependency is `httpx` (plus `tzdata` on Windows).
+
+## Five rules the library never breaks
+
+1. **Every order is idempotent.** The library generates the `client_order_id` and
+   fsyncs it to a local journal before the request leaves the process. Any retry,
+   including one after a crash and restart, reuses that key, so the same order is
+   never placed twice.
+2. **No invented outcomes.** An order ends in the state the API reports. When an
+   answer is lost, the order is reported as `unknown` while the platform checks
+   with the broker. It is never re-sent under a new key.
+3. **Config is data, code is strategy.** The connection, the account, the local
+   risk envelope and the schedule come from a properties file or environment
+   variables. Tokens are never logged.
+4. **One run at a time.** `on_run` is never called twice at once for the same
+   strategy.
+5. **Closing always works.** `close()` and `cancel_order()` are sent during a
+   halt and after a risk rule trips, exactly as the API allows. The library adds
+   no block of its own.
+
+## Quick start
+
+```python
+from perkbridge import Config, Connect
+
+conf = Config.load()          # ./perkbridge.properties, $PERKBRIDGE_CONFIG, env
+pb = Connect(conf)            # checks the token and the account
+
+print(pb.account().balance, pb.quote("EURUSD").ask)
+order = pb.buy("EURUSD", volume="0.01", then_stops=("1.0800", None))
+print(order.status)           # filled, placed, refused, rejected, ... or unknown
+pb.close(pb.position("EURUSD"))
+```
+
+A strategy:
+
+```python
+from perkbridge import Context, Strategy, run
+
+class Breakout(Strategy):
+    config = {"schedule.mode": "interval", "schedule.every": "1h",
+              "schedule.market_hours": "Mon-Fri 08:00-20:00"}
+
+    def on_run(self, ctx: Context) -> None:
+        bars = ctx.bars("EURUSD", "H1", limit=21)
+        if ctx.position("EURUSD") is None and bars[-1].close > max(b.high for b in bars[:-1]):
+            ctx.buy("EURUSD")
+
+run(Breakout)
+```
+
+or from the command line:
+
+```
+perkbridge-run examples/breakout.py:Breakout --config examples/breakout.properties
+```
+
+See [examples/breakout.py](examples/breakout.py) for a complete strategy.
+
+## Configuration
+
+Settings are layered: the strategy's `config` defaults, then the file, then
+`[strategy.<name>]` sections, then environment variables. Values set in code
+with `Config.update()` win over all of these. Unknown keys and invalid values
+are all reported at start, with a hint.
+
+```properties
+connection.url     = https://connect.example.com
+connection.account = tac-7f3k2m9q
+# connection.token: prefer PERKBRIDGE_CONNECTION_TOKEN or ..._TOKEN_FILE
+order.default_volume     = 0.01
+order.max_open_positions = 3        # local envelope, refused before sending
+order.max_volume         = 0.10
+order.allowed_symbols    = EURUSD, GBPUSD
+state.dir = ~/.perkbridge/state
+
+[strategy.breakout]
+schedule.mode  = interval
+schedule.every = 1h
+```
+
+- **Environment variables.** Every key has one: `connection.token` becomes
+  `PERKBRIDGE_CONNECTION_TOKEN`. A `_FILE` suffix reads the value from a file,
+  which suits Docker secrets. A value written `${env:NAME}` in the file reads
+  the variable `NAME`.
+- **File permissions.** A file that holds a token must not be readable by other
+  users; the library refuses it and suggests `chmod 600`.
+- **Plain HTTP.** Accepted only for `localhost`.
+- **Checking a config.** `perkbridge-run --show-config` prints the merged
+  settings and where each one came from, with the token masked.
+
+| Group | Keys |
+|---|---|
+| `connection.` | `url`, `token`, `account`, `timeout_s`, `verify_tls`, `ca_file` |
+| `order.` | `default_volume`, `expires_in_ms`, `wait_for_outcome`, `wait_timeout_s`, `strict`, `stops_watch_s`, `max_open_positions`, `max_volume`, `allowed_symbols`, `max_orders_per_run`, `duplicate_check`, `replay_window_s` |
+| `state.` | `dir` |
+| `schedule.` | `mode` (manual, interval, at, cron), `every`, `at`, `cron`, `timezone`, `align`, `market_hours`, `skip_if_running`, `catch_up`, `jitter_s`, `max_consecutive_errors` |
+| `events.` | `enabled`, `poll_interval_s` |
+| `log.` | `level`, `format` (text, json) |
+
+## Orders and outcomes
+
+- **Order calls.** `buy`, `sell`, `buy_limit`, `sell_limit`, `buy_stop`,
+  `sell_stop`, `buy_stop_limit` and `sell_stop_limit` return an `Order`. By
+  default the call waits until the order is final, placed or `unknown`.
+  `close`, `close_all`, `modify_position`, `modify_order` and `cancel_order`
+  work the same way. For modifies, `KEEP` leaves a value unchanged and `None`
+  removes it.
+- **Refusals and rejections.** The platform refusing an order raises
+  `OrderRefused`, with `.code` and a hint. The broker rejecting it raises
+  `OrderRejected`, with `.retcode`. Both carry the stored order.
+- **Stops on market orders.** When a symbol does not support stops on a market
+  order, the order is refused before it is sent (`StopsNotSupported`). Use
+  `then_stops=(sl, tp)` instead: it places the order, then modifies the
+  position. The stops are journaled with the order. If the order has not
+  filled when the call returns, they are set once it fills, and exactly once,
+  with the key `<key>-s`. This is checked on start, after `wait()`, on order
+  events, before each strategy run, and by `pb.apply_pending_stops()`. An order
+  that ends without a fill drops its stops.
+
+  While stops are waiting, a background watcher thread (a daemon) retries
+  every `order.stops_watch_s` (2 s by default), so a direct `Connect` user
+  needs no further call. The watcher stops when nothing is pending or on
+  `close_session()`. Closing, or the process ending, with stops still pending
+  logs a warning: those positions are not protected until a `Connect` for the
+  same account and `state.dir` starts again and resumes them. With
+  `order.stops_watch_s = 0`, the caller must call `apply_pending_stops()` or
+  `wait()` itself.
+
+  If the stops fail during the `buy()` call itself, the call raises
+  `StopsNotSet`, whose `.order` is the order that WAS placed. Do not place it
+  again. Inside a strategy, the same intent returns that order instead of
+  opening a second position. Stop intents that are not resolved, and orders
+  that are not final yet, are never pruned from the journal, however old they
+  are.
+
+  The stops count as set only when the platform reports the modify as
+  `done`. While the modify is queued, sending or unknown, it stays pending
+  and is followed up with the same key. These cases are handled as follows:
+
+  - **Nothing sent.** Another order was in flight, or the platform rate
+    limited the request. The modify is retried later.
+  - **Refused, rejected or expired.** The modify was definitely not applied. It
+    is retried with a fresh key (`<key>-s2`, `-s3`, ...), waiting 5 s, 15 s,
+    60 s, then 300 s between attempts.
+  - **Permanent refusal.** For example `stops_invalid` or
+    `position_not_found`. The library gives up and logs an error saying the
+    position is open without its stops.
+  - **Too many attempts.** After 20 attempts it also gives up with that error.
+  - **Position already closed.** The stops are dropped.
+
+  - `pb.pending_stops()` lists the stops that are still being worked on.
+  - `pb.stops_status()` lists every intent with its state: `pending`,
+    `failed`, `set`, `dropped` or `resolved`.
+  - `pb.stops_needing_attention()` lists positions left open without the
+    stops the library gave up setting. Each one stays listed, across restarts
+    and journal pruning, until its position is seen closed. Each one is also
+    logged as an error on start and before every strategy run.
+  Reusing a `client_order_id` with different `then_stops` raises
+  `IdempotencyConflict`.
+- **Unknown outcomes.** An `unknown` outcome is returned as an order with
+  `.unknown` true, or raised as `OutcomeUnknown` when `order.strict = true`. The
+  platform settles it, and `pb.wait(order)` or the events follow it.
+- **Duplicate intents.** Inside one strategy run, the same intent made twice
+  returns the first order (`order.duplicate_check`). If the first call ended
+  without a known outcome (`ConnectionLost`, `OutcomeUnknown`), the same intent
+  reuses the first call's key, so the platform answers with that order instead
+  of placing a second one. Only a definite "not placed" (refused, rejected,
+  never sent) frees the intent for a new order.
+- **Local envelope.** The envelope is checked inside the account's submission
+  lock, so two threads cannot both pass `order.max_open_positions`. It applies
+  only to a new intent: a replay of a `client_order_id` that is already
+  journaled returns the stored order even when the limit has been reached.
+- **One order in flight.** While an order of the account is still `sending`
+  or `queued`, the next order raises `InFlight` instead of queueing. This also
+  applies after `wait()` times out and after a restart, because the journal
+  remembers the order. An `unknown` outcome is left to the platform, which
+  refuses new orders with `reconciliation_pending` while it checks.
+- **`close_all`.** It closes positions one by one and stops at the first
+  close whose outcome is not known (a lost answer, or `unknown`). That close
+  stays journaled and is resolved with its key before anything else is sent.
+- **Keys that are never reused.** A journaled key whose request never got an
+  answer follows the restart rules even when it is reused at once: it is
+  looked up by key, replayed only while it is younger than
+  `order.replay_window_s`, and abandoned otherwise. An abandoned key raises
+  `OrderError` (`intent_abandoned`) and is never sent again; a new order needs
+  a new key. Derived keys, such as `<key>-s` for stops, stay unique for keys
+  near the 128-character limit, because they include a digest of the whole
+  key.
+- **Restarts.** On start, `Connect` reads the journal. An entry that never got
+  an answer is looked up by its key first. It is replayed with the same key only
+  if it is younger than `order.replay_window_s` (120 s by default); otherwise it
+  is reported and abandoned.
+
+## Strategies and the scheduler
+
+`Strategy` has four callbacks: `on_start`, `on_run`, `on_event(ev)` and
+`on_stop`.
+
+- **The context.** `ctx` exposes the reads and orders, scoped to the
+  strategy's own positions unless `all=True`. It also has `ctx.state`, a dict
+  persisted between runs, plus `ctx.run_number`, `ctx.now` and `ctx.log`.
+- **Schedules.** `interval` (aligned to the clock by default), `at` (fixed
+  times), `cron` (five fields) and `manual`. All of them honour
+  `schedule.timezone` and daylight saving time, and can be limited with
+  `schedule.market_hours`.
+- **Missed and failing ticks.** A tick that overruns is skipped, not stacked.
+  Missed ticks after a sleep run once at most, or are skipped. After
+  `schedule.max_consecutive_errors` errors in a row, the strategy pauses with a
+  clear log line.
+- **Control Plane unreachable.** The tick is skipped with one log line. Nothing
+  is closed or retried blindly.
+- **Events.** They come from the account's event feed, with a saved cursor, so
+  none are lost across restarts. A cursor that is too old resynchronises and
+  delivers a `sync.resumed` event.
+
+## Time Machine
+
+Replay a strategy over a past window with `ctx.now` set to each past tick:
+
+```
+perkbridge-run examples/breakout.py:Breakout -c examples/breakout.properties \
+    --time-machine from=2026-10-01 to=2026-10-31 step=1h
+```
+
+- **Data.** Bars come from the API, and only bars closed before `ctx.now` are
+  visible. Quotes are synthetic, built from the last M1 close plus the live
+  spread.
+- **Fills.** A local simulator fills market, limit, stop and stop-limit orders
+  and SL/TP on M1, M15 or H1 bars, depending on the window length.
+- **No real orders.** Nothing is sent to the platform. `orders=none` only logs
+  the intents.
+- **Output.** The report is written to
+  `state/<account>/strategies/<name>/time-machine/<from>_<to>/report.json`.
+
+It is a sanity replay, not a backtester: there are no swaps, commissions or
+slippage model.
+
+## Command line
+
+```
+perkbridge-run TARGET [--config FILE] [--set KEY=VALUE ...]
+               [--check | --show-config | --once | --time-machine ... | --reset-state --yes]
+```
+
+- **Target.** `TARGET` is `module:Class` or `file.py:Class`, with
+  `Class1,Class2` for several strategies.
+- **Exit codes.** 0 means OK, 1 an error, 2 a configuration error and 130
+  interrupted.
+- **Logs.** They are JSON when stdout is not a terminal.
+- **Tokens.** `--set connection.token=...` is refused: tokens do not belong on
+  command lines.
+
+## Running in a container
+
+The library is built to run in a container later, with no code change:
+
+```yaml
+services:
+  breakout:
+    image: python:3.12-slim          # an official image will follow
+    command: perkbridge-run /app/breakout.py:Breakout
+    environment:
+      PERKBRIDGE_CONFIG: /app/perkbridge.properties
+      PERKBRIDGE_CONNECTION_TOKEN_FILE: /run/secrets/perkbridge_token
+      PERKBRIDGE_STATE_DIR: /state
+    volumes: ["./app:/app:ro", "state:/state"]
+    secrets: [perkbridge_token]
+    stop_grace_period: 30s
+volumes: {state: {}}
+secrets: {perkbridge_token: {file: ./token}}
+```
+
+Keep `state.dir` on a volume: the idempotency journal is what makes a restart
+safe. The library warns when it runs in a container with the default `state.dir`.
+
+## Low-level API
+
+`pb.api` is a thin typed client with one method per public operation of the
+Trading API, for example `pb.api.list_orders(...)` and
+`pb.api.place_order(body)`. It handles authentication and retries but adds no
+journal.
+
+## Development
+
+```
+python -m venv .venv && . .venv/bin/activate
+pip install -e '.[dev]'
+ruff check . && ruff format --check . && mypy src && pytest
+```
+
+- **Unit tests** (`tests/unit`) use an in-process fake API and run anywhere.
+- **Contract tests** (`tests/contract`) run against a real Control Plane with
+  simulator accounts, built from the private `perkbridge/nile` source with
+  `tests/contract/nile-sim.sh`. They are skipped unless `PB_CONTRACT_URL` is
+  set.
+- **Specification.** See [docs/SPEC.md](docs/SPEC.md).
+
+## Licence
+
+Apache-2.0