<!--
  GENERATED — do not edit this repository directly.

  Every file here is built from the outcometick monorepo by
  scripts/publish-sdk-repos.mjs and overwritten wholesale on each publish.
  An edit made here survives until the next publish and then disappears.

  Generated from monorepo revision e035dda7a86e04d3656384149e92ba251bc51c95.
-->

# outcometick

The TypeScript / JavaScript strategy SDK and the `ot` command line for
[outcometick.com](https://outcometick.com) — tick-level data for Polymarket and
Predict.fun crypto Up/Down markets.

```
npm i -g outcometick

ot check .                                           # validate, free, no data
ot run . --data ./polymarket-data-samples            # replay locally
ot submit . --assets btc,eth --days 30               # send it to the queue
ot status <run_id>                                   # where it got to
ot fetch  <run_id>                                   # download the report
```

**Breaking in 2.0:** backtests cover only the most recent 35 archived
days, and the window moves forward as days are archived. A `--from` before the
window, or `--days` longer than it, is refused with `E_SCOPE` before anything
is uploaded, and the message names the current window. Use `--days <n>` for the
most recent n days; the current dates are at
`https://outcometick.com/v1/backtest/capacity?venue=polymarket`.

## Writing a strategy

Fully typed — `ot` ships `.d.ts` declarations, so a strategy that type-checks
is one the queue will accept.

```ts
import { Strategy, Order, type Ctx, type Tick } from "outcometick";

export default class MeanReversion extends Strategy<{ entry_z: number; size: number }> {
  private entered = false;

  onMarketOpen() { this.entered = false; }

  onTick(ctx: Ctx<{ entry_z: number; size: number }>, tick: Tick): Order | null {
    const z = ctx.zscore(tick.value, { window: 180 });
    if (this.entered || Math.abs(z) < ctx.p.entry_z) return null;
    const side = z > 0 ? "DOWN" : "UP";
    const limit = ctx.book().best(side);
    if (limit === null) return null;
    this.entered = true;
    return new Order({ side, size: ctx.p.size, limit });
  }
}
```

Plain JavaScript works too — the runtime is ESM with no build step.

## The point of `ot check`

It runs the **same validator the queue runs** — the same module, not a copy. If
it passes locally it will not be rejected on submit. That is only true because
there is one implementation, which is why the validator and the static analysers
ship in this package rather than being reimplemented client-side.

## What `ot run` is and is not

It is the same engine, the same report and the same archive format the queue
uses, against a local copy of the archive:

    curl -L https://github.com/outcometick/polymarket-tick-data-samples/releases/latest/download/polymarket-data-samples.tar.gz | tar xz

It is **not** the sandbox. Locally your strategy runs as you, with your
privileges, on your machine — which is fine, because it is your code. On our
machines it runs in a container with no network, no writable filesystem and a
hard CPU and wall-clock budget.

## Testing

```
npm install && npm test
```

Requires `python3` on PATH: one of the two static analysers is written in
Python, and the CLI drives it the same way the API does.

## Downloading data

The other half of the package: a client for the data subscription, on a
separate import because it has nothing to do with writing a strategy.

```ts
import { DataClient, NO_VALUE } from "outcometick/data";

const ot = new DataClient();                    // key from OT_KEY

const meta = await ot.meta();                   // what can this key see?

const { files } = await ot.files({
  from: "2026-08-01", to: "2026-08-12",         // or date: "2026-08-12"
  asset: ["BTC", "ETH"],                        // the BASE symbol, not BTCUSD
  dataset: "prices",
  interval: ["5m", NO_VALUE],                   // "5m" alone EXCLUDES the
});                                             // period-less settlement streams

await ot.download(files[0], { saveTo: files[0].name });   // checksum verified
```

`meta()` reports the dimensions this key can actually reach. Note that
`intervals` holds real durations only — the `none` sentinel is reported
separately under `filterTokens`, so a caller that builds an enum from it or
parses the values as durations never meets a token.

Downloads are checksum-verified: `/v1/dl` redirects to storage with the sha256
in a header, and the client follows that redirect itself so the checksum is not
thrown away.

### Rebuilding a Polymarket order book

`book` and `price_change` are stored at a capture cadence, so a removal can
fall between two stored frames and leave a stale level behind. `OrderBook`
applies the documented rebuild rule: snapshots replace a token's
ladder, changes set absolute sizes (0 removes), and levels crossed by the newest
best bid/ask (from `best_bid_ask` and from each change) are dropped. Feed it
rows from the three files merged by `recv_ms`.

```ts
import { OrderBook } from "outcometick/data";

const book = new OrderBook();
for (const row of rows) book.apply(row);       // parsed objects or JSONL lines
book.ladder(tokenId);                           // { bids: [{ price, size }], asks: [...] }, best first
book.best(tokenId);                             // { bid, ask }
```

That removes every level the best prices have moved past, but it cannot
restore what the dropped frames added or resized: until the next snapshot a
level, at the top too, can be missing or carry an old size (`best_bid_ask` has
prices only). `best()` is the best level of the rebuilt ladder, not the
market's latest best bid/ask — read `best_bid_ask` rows for that.

### Smart-money trade history

A separate subscription with its own key: daily files of the trades made by the
top-ranked Polymarket traders.

```ts
const smart = new DataClient({ key: process.env.OT_SMART_KEY });
const { days } = await smart.smartDays();                  // newest first
const day = days.find((d) => d.lists.top100?.status === "published")?.day;
if (day) await smart.smartDownload(day, "top100", { saveTo: "top100.csv.zst" });  // verified
```

What the lists are and what each column means:
https://outcometick.com/polymarket-smart-money-data

## MCP server

`ot mcp` is a Model Context Protocol server over stdio, for coding assistants
and agents. It reads, prices, validates and downloads; it never submits a
backtest, because that spends credits. Needs Node 24 or newer.

```json
{
  "mcpServers": {
    "outcometick": {
      "command": "npx",
      "args": ["-y", "outcometick", "mcp"],
      "env": {
        "OT_KEY": "<data subscription key, optional>",
        "OT_SMART_KEY": "<smart-money key, optional>",
        "OT_BACKTEST_KEY": "<backtest key, optional>"
      }
    }
  }
}
```

Claude Code: `claude mcp add outcometick -e OT_KEY=<data key> -- npx -y outcometick mcp`

The same tools are also hosted, with nothing to install, over Streamable HTTP:

- `https://outcometick.com/v1/mcp`: send `Authorization: Bearer <key>` (data, smart-money or backtest key; add a second or third key as `X-Backtest-Key` / `X-Smart-Key`), or connect without a header and sign in with OAuth, pasting your keys on the consent page (claude.ai and ChatGPT connectors).
- `https://outcometick.com/v1/mcp/public`: no key, public tools only.

`claude mcp add --transport http outcometick https://outcometick.com/v1/mcp --header "Authorization: Bearer <data key>"`

Hosted, `download_file` and `smart_download` return a signed URL and its sha256 instead of writing to disk, and `check_strategy` takes the file contents instead of a directory.

| Tool | Key | What it does |
| --- | --- | --- |
| `coverage` | none | What the archive holds per venue: assets, datasets, day range |
| `plans` | none | Data subscription plans and their live prices |
| `backtest_capacity` | none | Which days can be backtested now, and how busy the queue is |
| `backtest_quote` | none | Price a backtest scope in credits without submitting it |
| `check_strategy` | none | Validate a strategy directory with the queue's own validator, locally |
| `meta` | `OT_KEY` | The date window and filter values the data key can reach |
| `list_files` | `OT_KEY` | Search archive files the data key can download |
| `download_file` | `OT_KEY` | Download one file and verify its sha256 |
| `backtest_runs` | `OT_BACKTEST_KEY` | Recent runs under the backtest key, and the credit balance |
| `backtest_status` | `OT_BACKTEST_KEY` | One run's status, credits and report summary |
| `smart_plans` | none | Smart-money plans (daily Polymarket wallet lists) and their live prices |
| `smart_coverage` | none | Which smart-money days are published |
| `smart_days` | `OT_SMART_KEY` | The days the smart-money key can download, with each list's status |
| `smart_download` | `OT_SMART_KEY` | Download one day's list and verify its sha256 |

---

Writing your strategy in Python instead? The SDK for it is
[`pip install outcometick`](https://pypi.org/project/outcometick/). `ot` runs
those too — it is the one CLI for both languages.

Full reference: https://outcometick.com/docs/sdk

## Links

- [outcometick.com](https://outcometick.com) — what this is, and what the data covers
- [Run a backtest](https://outcometick.com/backtest) — paste a strategy, watch it run
- [SDK reference](https://outcometick.com/docs/sdk) — manifest, hooks, `ctx`, limits
- [Data API](https://outcometick.com/docs) — the archive these strategies read
- [Discord](https://discord.gg/ZDMqkptwm5) (English and 中文) and [Telegram](https://t.me/+TcK_hJOzOz5mZTk1) — questions and strategy talk