// STRATEGY SDK · v3.1.0

Writing a strategy

A strategy is one class plus an outcometick.json manifest. The runner calls your hooks tick by tick, in event-time order, inside a sealed container. The SDK is the same locally against the free sample files as it is here against the full archive, so what runs on your local machine runs here unchanged.

Execution model

The runner owns the loop. Your class implements hooks; it does not open files, read a clock, or make network calls. Events arrive in this order:

for each market-day in your scope (sharded across workers)
  on_market_open(ctx, market)     ← state resets here
  for each event in event-time order:
    on_tick / on_book / on_trade  ← you may return an Order
  on_settle(ctx, market, outcome) ← official label arrives last

Each market is independent: your instance state is discarded at every on_market_open, which is what lets us shard hundreds of market-days across workers.

What the runner does with your class

The solid boxes are the methods you write; the dashed ones are what the runner does between your calls.

You implement at least ONE of on_tick / on_book / on_trade — whichever streams you want to react to. on_market_open and on_settle are optional bookkeeping. The loop belongs to the runner: you never poll, sleep, or ask for the next event, and because the next row has not been read yet, there is nothing to peek at.

Your hook returns an order, and the runner matches it against the book that was actually resting at that millisecond. Fills, partial fills and walked depth are decided by the archive, not by your assumptions.

Install

The ot CLI lives in the npm package — install it globally or the command is not on your PATH. The pip package is the SDK surface for your editor and type checker; it does not carry ot. Versions are pinned per language and the runner uses the same ones: a mismatch is a rejection, not a warning.

# the ot CLI — check / run / submit (node 24, ESM only)
npm i -g outcometick@3.1.0

# writing in Python? add this for type hints in your editor.
# it does NOT contain ot — the line above is what gives you the command.
pip install outcometick==3.1.0

Quickstart

Two files is a complete submission. Python shown; Node.js has identical semantics with idiomatic names — see the parity table.

from outcometick import Strategy, Order


class MeanReversion(Strategy):
    def on_market_open(self, ctx, market):
        self.entered = False

    def on_tick(self, ctx, tick):
        # tick.value is the settlement feed's price, as a float
        z = ctx.zscore(tick.value, window=180)
        if self.entered or abs(z) < ctx.p.entry_z:
            return None

        side = "DOWN" if z > 0 else "UP"
        book = ctx.book(tick.market_id)
        if book.depth(side) < ctx.p.min_depth:
            return None

        self.entered = True
        return Order(side=side, notional=ctx.p.notional,
                     limit=book.best(side),
                     hold_s=ctx.p.hold_minutes * 60)

{
  "schema": 1,
  "language": "python@3.14",
  "entry": "strategy.py:MeanReversion",
  "hooks": ["on_market_open", "on_tick"],
  "datasets": ["settlement", "book"],
  "deps": ["numpy"],
  "params": {
    "entry_z": 2.0,
    "hold_minutes": 20,
    "notional": 200,
    "min_depth": 2000
  }
}

Start from a template

Two working strategies ship with the CLI, each in Python and Node.js. favourite-near-close buys, in the last minute, the side the settlement feed says is winning, while the book still sells it under a ceiling — it runs locally on the free sample. binance-lead takes the side Binance spot points at before the book catches up; it reads the Binance reference feed, so it runs on the hosted backtest. Both are also in the editor on the backtest page. They are starting points, not proven edges: one sample day says nothing about next month.

# list the templates
ot init

# copy one into a new directory (--lang python or nodejs)
ot init my-strategy --template favourite-near-close --lang python
ot check my-strategy

# replay it on the free sample day (download it once — see "Run it locally")
ot run my-strategy --data ./polymarket-data-samples

All templates, with a README per strategy: github.com/outcometick/polymarket-strategy-templates

Working from an AI coding tool? The same npm package includes an MCP server (ot mcp); setup is on the docs page.

Manifest reference

Without a valid outcometick.json a submission is not queued. It is also what the quote is computed from.

Which settlement stream applies

The venues changed what these markets settle on, and not all at once. Ask for settlement and each market is fed the stream IT actually settled on — read from that market's own config, never inferred from its date. You do not need to know the cut-over, and you cannot get it wrong.

Naming a captured stream outside the window we actually captured it in is E_COVERAGE, never a silent substitution. Every archive reports how many markets each settlement stream backed, so you can see the mix a run replayed.

Hooks

Implement what you need; declare exactly those in the manifest. An undeclared hook is never called, and a declared-but-missing hook is a rejection.

ctx

Everything the runner lets you touch is on this object. Anything not listed here is not in the process.

External data

You cannot fetch Binance mid-run. The sandbox has no network, and a live fetch would make the same code produce different reports on different days. Outside data is resolved into a dataset before the run starts and replayed on the same clock as everything else.

  "reference": ["binance:btcusdt:spot:1s"],
  "series": [{ "name": "my_signal", "file": "signal.csv" }]

# both are read-only and aligned to event time
spot = ctx.ref("binance:btcusdt:spot:1s").last
basis = tick.value - spot.close
mine = ctx.ext("my_signal").at(ctx.now)

A strategy that uses one

Fades the market when it disagrees with Binance spot momentum. The whole thing, so you can see where the feed comes into it.

{
  "schema": 1,
  "language": "python@3.14",
  "entry": "strategy.py:Basis",
  "hooks": ["on_market_open", "on_tick"],
  "datasets": ["settlement", "book"],
  "reference": ["binance:btcusdt:spot:1s"],
  "params": { "lookback_s": 30, "min_drift": 0.0004, "max_px": 0.6, "notional": 80 }
}

from outcometick import Strategy, Order


class Basis(Strategy):
    """Fade the market when it disagrees with Binance spot momentum."""

    def on_market_open(self, ctx, market):
        self.done = False

    def on_tick(self, ctx, tick):
        if self.done:
            return None

        spot = ctx.ref("binance:btcusdt:spot:1s")
        # Enough history to measure momentum over. Early in a market-day there
        # is not any, and None is what you get -- not a zero, and not a bar
        # borrowed from after ctx.now.
        bars = spot.window(ctx.p.lookback_s)
        if len(bars) < ctx.p.lookback_s:
            return None

        drift = (bars[-1].close - bars[0].close) / bars[0].close
        if abs(drift) < ctx.p.min_drift:
            return None

        # Spot is going up, so the market saying "down" is the side to take.
        side = "UP" if drift > 0 else "DOWN"
        book = ctx.book(tick.market_id)
        px = book.best(side)
        if px is None or px > ctx.p.max_px:
            return None

        self.done = True
        ctx.log(f"drift {drift:+.4%} over {ctx.p.lookback_s}s -> {side} at {px}")
        return Order(side=side, notional=ctx.p.notional, limit=px)

window(n) returns what has closed by ctx.now and nothing else — early in a market-day there is less than you asked for, which is why the length is checked rather than assumed. Note also: a 1s bar covering [t-1s, t] arrives at t, because it was not knowable at t-1s.

Bringing your own series

Attach a CSV with + outside data in the editor and it is declared for you. It is read on the same clock as everything else: at ctx.now you see the rows stamped at or before it, and nothing after.

ts_ms,score,confidence
1786536000000,0.62,0.91
1786536060000,0.58,0.88
1786536120000,0.71,0.95

{
  "schema": 1,
  "language": "python@3.14",
  "entry": "strategy.py:Signal",
  "hooks": ["on_tick"],
  "datasets": ["settlement", "prices", "twap30s", "twap60s", "book", "bbo", "spot", "trades", "markets"],
  "series": [{ "name": "my_signal", "file": "signal.csv", "lag_ms": 300000 }],
  "params": { "min_score": 0.6, "notional": 80 }
}

from outcometick import Strategy, Order


class Signal(Strategy):
    def on_tick(self, ctx, tick):
        row = ctx.ext("my_signal").last
        # None until the first row is BOTH stamped and past its lag_ms. The
        # column names are your CSV's own -- ts_ms is ours, the rest is yours.
        if row is None or row.score < ctx.p.min_score:
            return None

        book = ctx.book(tick.market_id)
        px = book.best("UP")
        if px is None:
            return None
        return Order(side="UP", notional=ctx.p.notional, limit=px)

If your signal is computed with a delay — a model that needs five minutes of data before it can score a minute — declare it with lag_ms and each row is held back that long. Without it a backtest reads a signal at a moment it could not have existed.

Both are point-in-time by construction: .at() and .last cannot see a row stamped after ctx.now, so a carelessly built signal file cannot leak the future into your backtest. If your series has a publication lag, declare it with "lag_ms" and we will hold each row back by that much.

Want reference data from an exchange we do not carry yet? Ask — adding a feed is usually quick.

Order

An Order is what a hook returns, not a request you send. The runner matches it against resting depth at that millisecond; an order larger than the visible size is partially filled and walked up the book, and the shortfall appears in the slippage report.

Worked examples

Three shapes that cover most of what people actually run on these markets. Every threshold is a param, so each one is a sweep away from being tuned.

1 · Late entry

Buy once, N seconds before settlement, only if the price sits in a band. The whole strategy is four params — and it lives or dies on the slippage and latency pages, because everyone else is doing the same thing at the same second.

def on_market_open(self, ctx, market):
    self.close_ts = market.close_ts_ms
    self.done = False

def on_tick(self, ctx, tick):
    secs_left = (self.close_ts - ctx.now) / 1000
    if self.done or secs_left > ctx.p.enter_at_s:
        return None

    ask = ctx.book(tick.market_id).best(ctx.p.side)
    if not ctx.p.px_min <= ask <= ctx.p.px_max:
        return None

    self.done = True
    return Order(side=ctx.p.side, notional=ctx.p.notional, limit=ask)

2 · Trend from the settlement stream

Same entry window, but the side comes from momentum on the underlying rather than the market's own price. The settlement stream is the Chainlink feed the market settles on, and you are already being fed it, so this needs no outside data and nothing to align. For momentum from an exchange instead, declare a reference feed — see External data.

def on_tick(self, ctx, tick):
    secs_left = (self.close_ts - ctx.now) / 1000
    if self.done or secs_left > ctx.p.enter_at_s:
        return None

    # Momentum on the underlying, straight off the settlement stream —
    # the same Chainlink prints this market settles on. No outside feed,
    # and nothing to align: it is the series you are already being fed.
    past = ctx.history(ctx.p.lookback_s + 1)
    if len(past) <= ctx.p.lookback_s:
        return None
    mom = tick.value / past[0].value - 1

    if abs(mom) < ctx.p.mom_threshold:
        return None

    side = "UP" if mom > 0 else "DOWN"
    ask  = ctx.book(tick.market_id).best(side)
    if ask is None or not ctx.p.px_min <= ask <= ctx.p.px_max:
        return None

    self.done = True
    return Order(side=side, notional=ctx.p.notional, limit=ask)

3 · Repeated trading inside one market

Aggressive, in and out of the same market as the signal flips. Drive it from on_book rather than on_tick so you react to book updates as they arrive, use reduce_only to flatten, and return a list when you want to flip in one event. This is a taker strategy: it crosses the spread.

def on_book(self, ctx, event):
    book = ctx.book()  # the event is the change; this is the book it produced
    edge = ctx.p.fair - book.best("UP")   # your signal
    pos  = ctx.position()

    # flat, and the edge is worth crossing for
    if pos.size == 0 and edge > ctx.p.entry_edge:
        return Order(side="UP", size=ctx.p.clip, limit=book.best("UP"))

    # edge gone — flatten
    if pos.size > 0 and edge < ctx.p.exit_edge:
        return Order(side="UP", size=pos.size, reduce_only=True,
                     limit=book.best_bid("UP"), tag="exit")

    # signal flipped — close and reverse in one event
    if pos.size > 0 and edge < -ctx.p.entry_edge:
        return [
            Order(side="UP", size=pos.size, reduce_only=True, limit=book.best_bid("UP")),
            Order(side="DOWN", size=ctx.p.clip, limit=book.best("DOWN")),
        ]

    return None

Not supported yet

Determinism rules

Two runs of the same code over the same range must produce byte-identical reports, otherwise the number we hand you means nothing. These are enforced statically at import and structurally at run time — the APIs are absent, not merely blocked.

• ABSENTNetwork. No sockets, no DNS, no HTTP client in the image.
• ABSENTFilesystem writes outside a scratch tmpfs, and reads outside your own files.
• ABSENTWall clock, timezone, locale, environment variables, process id, hostname.
• REJECTEDthreads, subprocess, eval, exec, dynamic import, reflection, native extensions.
• REJECTEDUnseeded randomness. Import-time static analysis catches it before the run starts.
• REJECTEDImports outside the allowlist, including transitive ones.
• REJECTEDPatching built-ins (Node.js): the standard built-ins (Object, Function, Array, Map, Set, String, Number, Math, Promise, Buffer and the rest) and their prototypes are locked before your code loads, and so are their global names, because the engine keeps its state in them and reads its input through them. Giving your own object its own toString still works.
• REQUIREDSerialisable instance state. We shard by market-day across workers, so state must survive a move.

Limits

Session mode lifts the per-market state reset so one instance sees every market in the range in a single ordered stream — portfolio limits, cross-market hedges, capital allocation. It costs the same as market mode: a market-day is a credit whichever mode reads it. Declare it with "mode": "session".

What you submit

A directory. The manifest has to be called outcometick.json and sit at its root; everything else is whatever your entry point imports. The web editor shows you both filenames as tabs — from the command line they are yours to create, so here they are.

my-strategy/
  outcometick.json     # the manifest: language, entry, hooks, datasets, params
  strategy.py          # the file `entry` points at, holding the `entry` class
  helpers.py           # split it up if you like
  signal.csv           # your own series, declared under `series`

# python: import your own files RELATIVELY, or the validator rejects them —
#   from .helpers import cheaper      ✓
#   from helpers import cheaper       ✗ E_IMPORT: not on the allowlist
# node:   import { cheaper } from "./helpers.mjs";

# the directory IS the submission — that is what the "." refers to
ot check  ./my-strategy
ot submit ./my-strategy --assets btc --days 20 --venue polymarket

Up to 6 files, of which at most 256 KB may be source: a declared CSV series counts against the file count but has its own byte budget, 4 MB each, and goes straight to storage rather than through the API.

Run it locally first

The SDK ships the same runner we use. Point it at the free sample repository, get the contract right, then spend credits on the full archive.

# one day of real files, free, no key needed
curl -L https://github.com/outcometick/polymarket-tick-data-samples/releases/latest/download/polymarket-data-samples.tar.gz | tar xz

# validate the manifest and hook signatures — no data touched, no key needed
ot check .

# replay locally, same runner, same report format
ot run . --data ./polymarket-data-samples

ot check runs the exact validator the queue runs. If it passes locally it will not be rejected on submit.

Or with no Node at all: pip install outcometick, and outcometick.backtest runs the same decoder, engine and report in-process — the class straight from your notebook, the sample downloaded once, decoded days cached so the next run starts at once.

# pip install outcometick
from outcometick import Strategy, Order
from outcometick.backtest import run, load_sample

class Favourite(Strategy):
    def on_market_open(self, ctx, market):
        self.close, self.done = market.close_ts_ms, False

    def on_tick(self, ctx, tick):
        if self.done or self.close - ctx.now > 60_000:
            return None
        up, down = ctx.book().best("UP"), ctx.book().best("DOWN")
        if up is None or down is None:
            return None
        self.done = True
        side, px = ("UP", up) if up >= down else ("DOWN", down)
        return Order(side=side, notional=50, limit=0.95) if 0.55 <= px <= 0.95 else None

result = run(Favourite, load_sample("polymarket"))   # or a directory of archive files
print(result.summary())

The backtester is open source, with the tests that compare the Python and JavaScript implementations event by event: github.com/outcometick/polymarket-backtest (Python) · github.com/outcometick/polymarket-backtest-js (JavaScript / TypeScript)

Its documentation — methodology, how it is verified, the Python API, and a page written for AI coding agents (with llms.txt): outcometick.github.io/polymarket-backtest

Submit & billing

From the command line, or from the editor on /backtest — the same queue either way. `ot check` runs the validator the queue runs, so a submission that passes locally will not be rejected here.

Breaking in SDK 2.0 — date window. Backtests cover only the most recent 35 archived days, and the window moves forward as new days are archived. A range starting before it, or a day count longer than it, is refused with E_SCOPE, and the message names the current window and what to change. Use --days <n> for the most recent n days; the editor on /backtest only offers dates inside the window. The current dates are at GET /v1/backtest/capacity?venue=<venue> (first_complete_day..last_day).

# the key travels in the environment, never in a flag:
# a flag lands in shell history and in the process list, and this key spends money
export OT_BACKTEST_KEY=bt_...

# submit to the queue: the most recent 10 archived days of two assets
# (backtests cover only the most recent 35; --from/--to must fall inside them,
#  and one run replays at most so many market-days: maxMarketDaysByShape in /v1/backtest/contract)
ot submit . --assets btc,eth --days 10

# where it got to, and what it actually cost
ot status run_...

# download the archive once it is done
ot fetch run_...

Credits are spent only on a run that produces a report. Rejections, compile errors, timeouts and crashes cost nothing — you get the validator output or stderr and the archive is never created.

Rejection codes

Except for E_RUNTIME, every code listed here comes back from ot check before you spend anything. E_RUNTIME is the one that cannot: it means the run was already executing, so it is refunded in full rather than prevented.