API reference · Sim

Run a simulation

POST/v1/sim/runs

Replay a past event against its recorded order books with a built-in strategy, at several latencies, and get the scorecard.

On this page

Auth. An API token: Authorization: Bearer lb_… (create one). Signed-in web sessions work too.

Limits. One Sim run (20 a month on Free, 100 on Builder, unlimited on Standard).

Parameters

Body

Name	Type	Required	Description
`event_id`	string	yes	A replayable event (`ev_…`); see List replayable events.
`strategy`	string	no	A built-in strategy name; see List built-in strategies. Default `hold_none`.
`params`	object	no	The strategy's parameters; unknown names are refused.
`latency_ms`	array of integer	no	Milliseconds after each event's emission to evaluate fills at, up to 6 values; default `[250, 2250, 5250]`.
`starting_cash`	number	no	Paper cash in USD. Up to 10,000,000. Default `1000.0`.
`maker_fee_rate`	number	no	The maker fee rate. 0 to 0.5. Default `0.0175`.
`queue_position`	boolean	no	Make resting orders wait behind the size recorded at their price. Default `false`.
`taker_delay_ms`	integer	no	A venue speed bump on taking orders, in ms. 0 to 60,000. Default `0`.
`code`	string	no	Refused. Your own strategy files run on your machine with `langbot sim run -s my_bot.py`.

Request

Terminal

curl -X POST "https://api.langbot.ai/v1/sim/runs" \
  -H "Authorization: Bearer $LANGBOT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event_id": "ev_kxearningsmentiongs_26oct13", "strategy": "buy_yes_on_first_counting_hit", "params": {"max_price": 0.6}}'

Python

from langbot import LangbotClient

async with LangbotClient() as lb:  # reads LANGBOT_API_TOKEN
    run = await lb.sim_run(
        "ev_kxearningsmentiongs_26oct13",
        "buy_yes_on_first_counting_hit",
        params={"max_price": 0.6},
    )
    print(run["id"], run["scorecard"]["by_latency"])

TypeScript

const res = await fetch("https://api.langbot.ai/v1/sim/runs", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.LANGBOT_API_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({"event_id": "ev_kxearningsmentiongs_26oct13", "strategy": "buy_yes_on_first_counting_hit", "params": {"max_price": 0.6}}),
});
console.log(await res.json());

Response

201 Created

JSON

{
  "id": "run_01K8Z3…",
  "kind": "server",
  "event_id": "ev_kxearningsmentiongs_26oct13",
  "strategy": "buy_yes_on_first_counting_hit",
  "params": { "max_price": 0.6 },
  "latency_ms": [250, 2250, 5250],
  "starting_cash": 1000.0,
  "paid": false,
  "created_at": 1793500000000,
  "scorecard": {
    "books_replayed": 18342,
    "by_latency": [
      { "latency_ms": 250, "net": 41.2, "fees": 3.1, "fills": 4, "fill_rate": 1.0, "max_drawdown": 6.0 },
      { "latency_ms": 2250, "net": 18.7, "fees": 3.3, "fills": 4, "fill_rate": 1.0, "max_drawdown": 9.5 },
      { "latency_ms": 5250, "net": -4.9, "fees": 2.4, "fills": 3, "fill_rate": 0.75, "max_drawdown": 14.0 }
    ],
    "markets": []
  },
  "allowance": { "plan": "free", "runs": 20, "period": "month", "used": 3, "remaining": 17, "resets_at": 1793577600000 }
}

A scorecard describes what the strategy would have done against the recorded books, after the venue's fees; it is not a forecast. How fills and fees are modelled: Simulator and backtesting.

Errors

Status	`code`	When
400	`bad_request`	The body carries `code`: custom strategies run locally.
404	`not_found`	No recorded feed or no order books for the event.
413	`too_large`	Over 5 million book snapshots in the window; run it locally.
401	`auth_required`	No token was sent.
401	`token_invalid`	The token was not recognised (mistyped, revoked or expired).
422	`validation_error`	A parameter failed validation; `detail[].loc` names it.
429	`quota_exceeded`	This month's Sim runs are spent; `quota.resets_at` says when they reset.
429	`rate_limited`	Over your request budget; wait `Retry-After` seconds.

Every error body is {"detail": …, "code": "…"}; branch on code. All codes: Errors.