Metadata-Version: 2.4
Name: continual-exchange-sdk
Version: 0.2.1
Summary: Continual Exchange Python SDK: protocol client, reference bots, local runner
Author: Continual Research
License-Expression: Apache-2.0
Project-URL: Homepage, https://continualexchange.com
Project-URL: Documentation, https://continualexchange.com/docs/
Project-URL: Repository, https://github.com/continualresearch/continual-exchange-sdk
Project-URL: Issues, https://github.com/continualresearch/continual-exchange-sdk/issues
Keywords: algorithmic-trading,market-simulation,multi-agent,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# Continual Exchange — Python SDK

Write a bot in Python, run local matches against reference and house bots, and get
a verifiable replay. The SDK is a thin client over the NDJSON loopback-TCP
protocol — the Rust engine is authoritative; the SDK has no game logic beyond
convenience. Spawned bots receive `CE_BOT_ADDR=HOST:PORT`; `run_bot` connects
automatically.

> The SDK is public on PyPI. During the current staging preview, the engine
> repository and public-season submissions are not open yet; staging accounts,
> ratings, and results are test-only.

## Install

```bash
python -m pip install continual-exchange-sdk
```

Local matches become available when the engine source repository opens. At that
point, build the matching engine release once and point the SDK at its checkout:

```bash
git clone https://github.com/continualresearch/continual-exchange.git
(cd continual-exchange/engine && cargo build --release)
export CE_ENGINE_ROOT="$PWD/continual-exchange"
```

For SDK development, clone this repository and use an editable install:

```bash
git clone https://github.com/continualresearch/continual-exchange-sdk.git
cd continual-exchange-sdk
python -m pip install -e '.[dev]'
```

## Your first bot in 30 lines

```python
from ce_sdk import Bot, run_bot, new_order, BUY, IOC

class FirstBot(Bot):
    def on_start(self, ms):
        self.base = ms["base_price"]; self.cid = 0

    def on_tick(self, s):
        f = (s.signals or {}).get("s")      # FACTOR seats get a factor signal
        if f is None:
            return []                        # IDIO seat: skip in this toy bot
        out = []
        for inst, beta in ((0, 1.0), (1, 0.8), (2, 0.9)):
            fair = self.base + beta * f
            ask = s.best_ask(inst)
            if ask is not None and ask < fair - 3 and s.position[inst] < 90:
                self.cid += 1
                out.append(new_order(self.cid, inst, BUY, ask, 2, IOC))
        return out

run_bot(FirstBot())
```

See [`examples/first_bot.py`](examples/first_bot.py).

## Run a local match after the engine source release

```bash
python examples/run_demo.py          # reference bots + your bot, then verify
```

Or from code:

```python
from ce_sdk import run_local_match, verify_replay
r = run_local_match(
    ["python examples/first_bot.py", "python examples/quoter_bot.py"],
    seed="hello", manifest="../testkits/manifests/quick.json",
)
verify_replay(r["replay"])            # bit-identical re-execution
```

## Package a submission

```bash
ce-package "python bot.py" --source ./my-bot --out submission.zip
```

The package is reproducible, contains a versioned `submission.json` entrypoint,
rejects symlinks and unsafe paths, and enforces the 4 GiB uncompressed limit.
Packaging works without the engine. After the engine source release, append
`--smoke` to run a Bronze validation with four competitor seats and four
disclosed house bots. The validation requires at least one valid message, no
crash or suspension, and a replay that verifies exactly.

## Protocol crib

- Engine → bot (one JSON line each): protocol version 2 `MATCH_START`, `TICK`,
  `MATCH_END`; each carries `type`, version, match id, tick, and sequence.
- Bot → engine (one JSON line = array of 0+ messages): `NEW_ORDER`, `CANCEL`,
  `CANCEL_ALL`.
- `TickState` accessors: `best_bid(i)`, `best_ask(i)`, `mid(i)`, `.position`,
  `.cash`, `.signals`, `.signal_type`, `.trades`, `.bulletins`, `.fills`, `.acks`.
- Constants: `BUY/SELL`, `GTC/IOC`, instruments `A=0, B=1, I=2`.

## Reference bots (`ce_sdk.bots`)

`NoiseTrader`, `NaiveQuoter`, and `SignalFollower` are readable examples for
random flow, symmetric quoting, and private-signal trading. See
[`examples/`](examples/) and the public
[first-bot walkthrough](https://continualexchange.com/docs/first-bot/).

The public [protocol reference](https://continualexchange.com/docs/protocol/)
documents every wire field.

## Releases

PyPI publishing is release-only. Maintainers bump `project.version`, merge the
change, and publish a GitHub Release whose tag is exactly `v<project.version>`.
The release workflow builds and verifies both distributions, then publishes
them to PyPI using a short-lived OIDC credential. No PyPI API token is stored in
GitHub.
