read this before anything else
What you are building
Polytraders is a non-custodial platform for trading prediction markets with bots. Users create their own bots. We supply the guardrail bots that make those user bots safe to run, and an AI layer that helps users decide what to trade, place it well, and watch what happens next. The rest of this guide documents the fleet we supply. This page tells you what it is for.
The mistake to avoid
Most of this guide reads like an implementation manual for a 109-bot trading system that we own end to end. That is a fair description of the code you will write in your first month, and it is not a description of the product. The product is a platform. Somebody else's bot is the thing that trades. Our bots exist to constrain it, inform it, and explain it.
This distinction decides real design questions. It is why the bot contract is not one contract but two, why guardrails are a chain rather than a class, why "just call the venue client" is never an acceptable shortcut, and why an LLM response can never become an order on its own.
Three actors
The user's bot
Declares intent: what to look for, when to enter, how to scale out, when to stop.
Authored as rules.yaml, version-controlled per user.
Runs in a sandbox. Holds no keys, no venue client, no network access.
output → a proposed OrderIntent, nothing more
Our guardrails & services
The 109 specs in this guide. Guardrails vote on every proposal and can reject, downsize, or quarantine it. Signal services feed it data. Execution utilities shape the approved order. Governance services log and explain everything.
output → the only signed order that reaches the venue
The RiskGate →The AI assist layer
Three surfaces: help the user work out what to trade, help them place it inside the guardrail envelope, and monitor open positions, correlations, and risk in plain English.
output → a typed suggestion that still passes the chain
The three AI surfaces →The trust boundary
Everything above the line is untrusted and sandboxed. Everything below it is ours and signed. There is exactly one crossing point.
┌──────────────────────────── UNTRUSTED ─────────────────────────────┐
│ │
│ user rules.yaml AI suggestion manual click │
│ │ │ │ │
│ └──────────┬─────────┴───────────────────┘ │
│ │ │
│ proposed OrderIntent │
└─────────────────────┬──────────────────────────────────────────────┘
│ ← the ONLY crossing point
┌─────────────────────┼─────────────── TRUSTED (ours) ───────────────┐
│ │
│ RiskGate │
│ ├── killswitch ── hard, cannot be disabled │
│ ├── compliancegate ── hard, cannot be disabled │
│ ├── exposure / drawdown ── hard floor, user tunes above │
│ ├── self-trade / wash ── hard, cannot be disabled │
│ ├── stale-book / halt ── hard, cannot be disabled │
│ └── … remaining chain ── see the RiskGate page │
│ │ │
│ approved + shaped order │
│ │ │
│ signer ── scoped session key, whitelist, revocable │
│ │ │
└─────────────────────┬──────────────────────────────────────────────┘
▼
venue (CTFExchangeV2)A user bot cannot draw a line that skips a box. Neither can an AI suggestion, a manual override, or a strategy you write yourself.
the four invariants · these are not negotiable
- 1
The platform never holds user funds.
Keys stay in the user's wallet. There is no platform-controlled omnibus account, no internal ledger of custodied balances, and no code path that can move a user's assets without a signature the user authorised. If a feature needs custody to work, it does not ship.
- 2
A user bot never reaches the venue directly.
User-authored logic produces a proposal. It never holds a venue client, an API key, or a signer. Exactly one component signs and submits, and it is ours.
- 3
Guardrails cannot be configured away.
The user tunes thresholds inside bounds we set. The user cannot remove a guardrail from the chain, reorder the chain, or lower a hard cap below the platform floor.
- 4
AI never holds Trade authority.
Model output is advisory. An AI suggestion enters the same RiskGate as any bot intent and is subject to the same rejects. There is no path from a model response to a signed order that skips the chain.
If a design requires breaking one of these, the design is wrong. Escalate before writing code — do not work around it. See RiskGate and the signing model.
What this changes about the work
| If you assume… | …you will build the wrong thing | Instead |
|---|---|---|
| All bot code is ours and reviewed. | One Bot<I,O> contract, conventions enforced by code review, no resource limits. |
Two contracts. UserStrategy is narrower and sandboxed with hard budgets. |
| Guardrails are one class among five. | A user could compose a strategy that never consults them, or disable them in config. | Guardrails are a fixed chain on the single write path. Not opt-in. |
| Non-custodial is a marketing word. | A convenient service key "just for execution" that can move funds. | Scoped session keys, method whitelist, user-revocable, no platform signer. |
| AI is a feature we bolt on. | A model call that returns an order and a code path that submits it. | Three advisory surfaces, each emitting a typed suggestion that enters the chain. |
| The user configures our bots. | A settings screen over our 109 specs, and no authoring format. | The user authors rules.yaml. Our specs are the rails underneath it. |
What the user actually needs from us
Stated as user problems, because these are the acceptance criteria that matter:
- "I don't know what to trade." Discovery and fair-value services, plus AI surface A. Ends in a candidate list the user can act on, with provenance.
- "I don't know if my idea is any good." Backtest against retained order-book depth, not mid price. Replay and parity tooling.
- "I don't want to babysit it." The bot runs; guardrails hold the line; the user gets told when something needs a human.
- "I don't want to blow up." Exposure caps, drawdown limits, correlation and concentration monitoring, a kill switch that always works.
- "I don't understand what it did." Every decision carries a reason code and a plain-English explanation. AI surface C turns a position set into a paragraph.
- "I don't want you holding my money." Non-custodial, scoped, revocable.
Where to go next
User-bot contract
The sandboxed UserStrategy shape, resource budgets, and the rules.yaml authoring format.
RiskGate
The single write path and the mandatory guardrail chain that every intent passes.
Signing model
Session-key scope, method whitelist, grant and revoke, signature-refused handling.
AI assist
Trade determination, placement assistance, and position monitoring — all advisory.
Start here
The PR path. What to build first, in order, with a clear done-when for each.
The pipeline
Build status of the guardrail and service fleet we supply.