alphaboard
Python SDK for AlphaBoard — strategy-level monitoring and reconciliation for algorithmic traders. (Formerly stratops; renamed to the single brand in OPM-762.)
from alphaboard import AlphaBoard
tracker = AlphaBoard(
strategy="momentum_eth",
broker="hyperliquid",
account="main",
)
# Inside your trade execution function:
tracker.log_trade(symbol="ETH-PERP", side="buy", quantity=0.5, price=3800)
# ...and when the venue refuses an order (feeds the reject_rate alert):
tracker.log_reject(symbol="ETH-PERP", side="buy", quantity=0.5, reason="margin")
# Periodic sync:
tracker.sync_positions([{"symbol": "ETH-PERP", "quantity": 1.5, "avg_entry_price": 3750}])
tracker.log_equity(equity=50_000, cash=10_000)
tracker.heartbeat(open_positions=1)
Versions and change notes
Pass the code version the process runs, a git SHA or a script hash, and every trade and equity point carries it:
tracker = AlphaBoard(strategy="momentum_eth", broker="hyperliquid", account="main",
version="a1b2c3d")
When a fill or equity point reports a version the strategy has not run before,
the server marks the equity chart by itself ("Version a1b2c3d (was 9f8e7d6)").
The Strategy page can then split returns before and after the mark, and a
backtest uploaded with the same version is compared with that version's live
span only.
For a change the version does not capture, write a note:
tracker.annotate("Stop widened from 2 to 3 ATR", kind="params")
tracker.annotate("Moved to the new VPS", kind="broker", global_=True) # every strategy
kind is one of deploy, params, sizing, broker or note. Like every
other call, annotate() returns at once and never raises.
Configuration
Connection settings resolve in this order (highest priority first):
- Constructor parameters —
AlphaBoard(api_url=..., api_key=...) - Environment variables —
ALPHABOARD_API_URL,ALPHABOARD_API_KEY - Config file —
~/.alphaboard/config.toml(override path viaALPHABOARD_CONFIG) - Built-in defaults —
http://localhost:8000, no key
The legacy STRATOPS_* env vars and ~/.stratops/config.toml are still read
as a fallback (one-time deprecation warning) — switch to the new names.
Example ~/.alphaboard/config.toml:
api_url = "https://alphaboard.example.com"
api_key = "sk_..."
# Optional: turn on the durable spool (see below)
spool_dir = "C:/alphaboard-spool"
Is it actually connected? (alphaboard doctor)
Installing the SDK and seeing no errors proves nothing — the SDK never raises,
by design, so a completely misconfigured client looks exactly like a working
one from inside your strategy. alphaboard doctor is the one command that
answers am I being watched?:
alphaboard doctor
alphaboard doctor --api-url https://alphaboard.example.com --api-key sk_...
It runs four checks in order and stops at the first failure, so you fix causes rather than symptoms:
| Check | Answers |
|---|---|
api |
Is the server reachable, and is its database connected? |
auth |
Does your API key authenticate? |
probe |
Does ingestion accept a real write? |
coverage |
The census: every strategy and account, the age of each stream, and a verdict of LIVE / DEGRADED / SILENT. |
Exit codes make it usable from a scheduled task or a CI step: 2 if the API or the key is broken, 1 if everything is reachable but something is not reporting, 0 if all four pass.
Two properties are worth knowing about, because they are the difference between a diagnostic and a placebo:
- It creates nothing. The write probe is a single infrastructure heartbeat
that deliberately carries no strategy name. A probe posted under a real
strategy would refresh that strategy's heartbeat stream and forward a
success ping to its external monitor — so a strategy that had been dead for a
day would read LIVE on the very next line of the diagnostic's own output, and
its real alert would be silenced. Pass
--no-probeto skip the write entirely and run read-only. - Zero strategies is a failure, not a pass. "0/0 live" is technically full coverage and is exactly the reassuring lie that hides a pipe that was never connected.
Durable spool (no-data-loss mode)
By default the SDK buffers events in memory only — a crash or an extended
server outage can drop events (your trading is never affected either way).
Setting a spool_dir (constructor param, ALPHABOARD_SPOOL_DIR, or the config
file) turns on a disk-backed outbox:
tracker = AlphaBoard(strategy="momentum_eth", spool_dir="C:/alphaboard-spool")
- Events are mirrored to a SQLite WAL file by the background worker and
deleted only after the server confirms receipt — they survive
SIGKILL, power loss, and outages of any length. - Replays reuse the same idempotency keys and carry the original event timestamps, so the server deduplicates them: at-least-once on the wire, effectively-once end-to-end.
- The spool is bounded by rows, bytes, and age (defaults: 1M rows / 512 MB /
7 days; tune via
spool_max_rows,spool_max_bytes,spool_max_age_s). On breach it drops oldest and surfaces the count viatracker.spool_dropped_count— an indefinite outage can't fill your disk. - Any spool failure (disk full, locked, corrupt) degrades the SDK back to memory-only. Durability never becomes a new way to crash the host.
Backfill (historical seeding + gap recovery)
alphaboard backfill replays a historical CSV — a broker statement, a Zorro
log, your engine's own journal — through the server's batch endpoints with
deterministic idempotency keys (UUIDv5 of each row's business key), so
re-running the same file or window is a no-op, never a duplicate:
alphaboard backfill trades.csv --kind trades --strategy momo --broker ib --account main
alphaboard backfill equity.csv --kind equity --strategy momo --mapping '{"Time": "snapshot_at", "Equity": "equity"}'
alphaboard backfill positions.csv --kind positions --strategy momo --broker ib --account main --dry-run
--kindistrades,equity, orpositions;--mappingrenames CSV headers to canonical fields (same convention as the server's CSV import).--strategy/--broker/--accountfill in routing fields the CSV doesn't carry; columns present in the file win.--since/--untilwindow on the row's event time;--dry-runvalidates and counts without sending.- Rows must carry their original
executed_at/snapshot_at— backfill refuses to stamp wall-clock-at-import times onto history. - Also available in code:
tracker.backfill("trades.csv", kind="trades").
Design
The SDK is observation-path only. It never sits between your strategy and the broker. The single hard guarantee:
tracker.log_trade(...)returns in microseconds, never blocks, and never raises.
Every public method enqueues an event into a bounded in-memory deque (default 10 000 items, drop-oldest on overflow), and returns immediately. A daemon background thread batches events, posts them to the AlphaBoard API with exponential backoff, and never lets an exception escape back to user code.
If the AlphaBoard server is unreachable, events back up in the queue until it returns or the queue overflows. Your trading continues unaffected.
On process shutdown, an atexit hook drains the queue with a bounded timeout (default 5s) so events from the final loop iteration aren't lost.
Install
pip install alphaboard
That pulls in httpx and its transitive dependencies and nothing else —
eight packages total. The SDK deliberately has no dependency on the API server,
the dashboard, or anything else in the workspace, so it installs cleanly into a
strategy process that shares none of them.
Working on the SDK itself? Install it from a checkout instead:
pip install ./packages/sdk
Licence
Apache 2.0.
Metadata
Release files for alphaboard 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| alphaboard-0.2.0.tar.gz | 69.9 kB | With provenance | Details for alphaboard-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| alphaboard-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for alphaboard-0.2.0-py3-none-any.whl |
Total release size: 122.4 kB
Release files / alphaboard-0.2.0.tar.gz
| Download URL | alphaboard-0.2.0.tar.gz |
|---|---|
| Size | 69.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
eab71b82c7615ba353b83872e8bf7a5c74286f5fd90d4c06c7c8a05312496be2
|
|
BLAKE2b-256 checksum How to use checksums |
8b0daf1b42ad576e64788db6b0408af2ab32d97899a050260ac481575d2e7bcf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.
Transparency logRelease files / alphaboard-0.2.0-py3-none-any.whl
| Download URL | alphaboard-0.2.0-py3-none-any.whl |
|---|---|
| Size | 52.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ccaef3fb4d08bc6538334d920b5e4ff916e3d18585005e5c7322415f8d641ef9
|
|
BLAKE2b-256 checksum How to use checksums |
a7a20659c229e641226bf0503d7cded3f24c194b56d8ebb4dd4a2ff6aa04e981
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.
Transparency logSecurity for alphaboard 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for alphaboard-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.