continual-exchange-sdk 0.2.0

Continual Exchange Python SDK: protocol client, reference bots, local runner

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.

Install

python -m pip install continual-exchange-sdk

To run local matches, build the public engine once and point the SDK at its checkout:

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:

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

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.

Run a local match

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

Or from code:

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 and smoke-test a submission

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

The package is reproducible, contains a versioned submission.json entrypoint, rejects symlinks/path traversal, and enforces the 4 GiB uncompressed limit. The optional smoke gate runs the packaged bot in a Bronze-composition match, verifies the replay, and requires at least one valid message with no crash or suspension.

Protocol crib

• Engine → bot (one JSON line each): protocol-v2 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, SignalFollower — readable archetypes that double as balance-harness inputs. See examples/.

Full engineering guide: ../continual-exchange/docs/continual-exchange-implementation-guide.md. Protocol reference: ../continual-exchange/proto/README.md.

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.