# Hosted bots

> Langbot runs a built-in strategy for you, on paper against live markets first, then on your own Kalshi account in a sub-account that holds only your budget, with guardrails, versions, rollback and a kill switch.

Source: https://langbot.ai/docs/hosted-bots

Langbot runs your bot for you, around the clock: as a **preview** on paper against live markets
first, then, when you **promote** it, on your own Kalshi account. Every change is a version you can
**roll back** to. Today a hosted bot is one of Langbot's built-in strategies with your settings,
the markets it may trade, a budget and its guardrails; your own code is
[coming soon](#bring-your-own-code-coming-soon).

Three ways to drive it, all on the same bots:

- **Claude**, with the [Langbot plugin](https://langbot.ai/docs/claude-plugin): ask in plain words.
- **The web**: `langbot.ai/app/bots` → **New bot** (pick a strategy, the markets and a budget, deploy
  a preview), and each bot's page.
- **The command line**: `langbot bots deploy | hosted | promote | rollback | stop | logs`.

New here? [From Claude to a live bot in 10 minutes](https://langbot.ai/docs/claude-quickstart).

## Previews: paper first

Every new version of a bot starts as a **preview**: it trades on paper against the live order
books Langbot records, with the simulator's fill model (reaction time, depth, queue position) and
Kalshi's fees. No money moves. A preview shows its net result after fees, today's result, what it
holds, every fill and a log of everything it did.

```bash
langbot bots deploy "trump words" --strategy buy_yes_on_first_counting_hit \
  --series KXTRUMPSAY --budget 100 --schedule '{"windows": "calendar", "budget_per_window_usd": 20}'
```

### Which markets

A bot names what it may trade, and keeps picking up matching markets that are listed later:

| Selector | Example | Means |
|---|---|---|
| `series` | `KXTRUMPSAY` | every market in the series, now and later |
| `events` | `KXFEDDECISION-26DEC` | every market of an event |
| `tickers` | `KXCPI-26NOV-T0.3`, `KXCPI-26NOV*` | exact markets, or a pattern |
| `query` | `Trump` | markets whose title has these words |
| `category` | `economics` | the venue's category |
| `speaker`, `kind`, `calendar` | `powell`, `earnings`, `ev_…` | markets of events on Langbot's calendar |

### When it trades

`schedule` is optional: `start_at` and `end_at` (a bot that expires on its own), `windows:
"calendar"` (only around the scheduled events of its markets), recurring windows (`{"days":
["mon", "tue"], "start": "09:30", "end": "16:00", "tz": "America/New_York"}`) and
`budget_per_window_usd` (at most this much put at risk in each window, for example $20 per speech).
Outside its windows a bot opens nothing and cancels its resting orders; it keeps what it holds.

## Guardrails

Every bot starts with these on. You can change any of them; you can also switch one off, but only by
confirming it by name, because the bot can then lose its whole budget.

| Guardrail | Default for a $50 budget | What happens |
|---|---|---|
| Largest order | 10 contracts | a bigger order is refused |
| Largest order at risk | $10.00 | a costlier order is refused |
| Daily loss stop | $12.50 | the bot stops itself for good once it has lost this much in a UTC day |
| Orders per minute | 10 | more are refused |
| Stop after exchange errors | 3 in a row | the bot stops itself |

The **budget** is never off: a preview's paper cash, and on a live bot the most it can have at risk
(on a sub-account, also all the money it can reach). The **kill switch** always exists: Stop on the
page, `stop_bot` from Claude, or `langbot bots stop`. A live bot also stops itself when its
positions on Kalshi no longer match what it believes, when an order's state cannot be confirmed, or
when its market data goes stale under a resting order.

For several bots, optional **fleet limits** cap them together: how many may be live, the total at
risk, and a combined daily loss that stops every live bot.

## How many bots run at once

Your plan sets how many bots may run a preview and how many may run live at the same time, and how
far back their logs go. A stopped bot does not count; a new version of a running bot replaces it
rather than taking a second place.

| | Free | Pro | Team | Enterprise |
|---|---|---|---|---|
| Paper bots running | 3 | 25 | unlimited | unlimited |
| Live bots running | 1 | 5 | 25 | custom |
| Always-on code bots (soon) | 1 small | 5 | 25 | custom |
| Bot logs | 24 hours | 30 days | 90 days | custom |

Past the limit, a deploy or promote answers `402` with `code: quota_exceeded` and `quota:
{dimension: "paper_bots" | "live_bots", plan, used, limit}`; stop a bot or upgrade. `GET
/v1/hosted/bots` returns the limits with what is in use. See [Pricing and limits](https://langbot.ai/docs/pricing).

## Live, on your own Kalshi account

Live hosted bots are for Kalshi accounts in the US. Langbot never holds your money and never takes
deposits: the bot trades in your Kalshi account, with a key that cannot move money.

### Connect Kalshi (one page)

On the bot's page choose **Connect Kalshi to go live**. This page is the only place a Kalshi key is
ever entered; never paste a key into a chat.

**Recommended: a sub-account with only the budget.** Create an API key in Kalshi (or use the one you
have), paste its id and private key, choose a budget and confirm the transfer. With that key, once,
Langbot:

1. reads your Kalshi API tier. Kalshi gives sub-accounts to accounts on its Advanced API tier, which
   requires at least one of your last 100 orders to have been placed through the API; on Basic,
   Langbot asks Kalshi for the Advanced grant. Langbot never places an order to qualify;
2. creates a new sub-account;
3. moves your budget into it from your main Kalshi balance (once; a retry never moves it twice);
4. creates a new key restricted to that sub-account with only `read` and `write::trade`: it can read
   and trade there and cannot transfer money or manage your account;
5. checks the new key with Kalshi and stores only it, encrypted. The key you pasted is not kept;
   delete it in Kalshi if you made it for this.

Kalshi itself now caps the bot at the budget.

**If your account cannot have sub-accounts yet,** the page says so and offers the main account: a
key that can only read and trade is created on your main account and nothing is moved. Kalshi then
caps nothing; the budget and the stops are Langbot's guardrails. It is labelled as such and must be
confirmed. Do not trade by hand on that account while the bot runs: a mismatch stops the bot.

**Advanced: your own restricted key.** In Kalshi, create the sub-account, move the budget and create
a key restricted to it with `read` and `write::trade`, then paste it. Langbot refuses a key Kalshi
does not accept, a key with any transfer or account permission, and a key that is not restricted to a
sub-account (unless you choose the main-account option on purpose).

### Go live

Strategies that take liquidity can go live today (the word strategies and buying No on long
shots); strategies that rest orders on the book (market making) stay on paper for now.

Once connected, **Promote** takes the newest preview live as a new live version (the preview keeps
running beside it). Every live order goes through the same guard as `langbot live run`: checked
against the guardrails, sent once with a fixed client order id, and written to the bot's log.
The live result shown is your Kalshi balance and positions.

How the strategy decides: on Langbot's recorded books and phrase hits, a few seconds behind the
exchange; each order is priced from a fresh Kalshi book at the moment it is sent, no more than 3
cents through the best price.

### Versions and rollback

Each change is a new **deployment**: an immutable version of the strategy, settings, markets, budget
and guardrails, with its own fills, positions, P&L and log. Promote one, roll back to an earlier one
in one step; the page lists them all.

### Disconnect

**Disconnect** on the connect page stops live trading and deletes the stored key. The key itself
stays in Kalshi until you delete it there.

## How your key is kept

- It is entered only on langbot.ai while signed in. Langbot's API refuses key material from API
  tokens, so it cannot arrive through the MCP or a chat.
- It is encrypted at rest: a fresh 256-bit data key per bot seals it with AES-256-GCM, and that data
  key is sealed with Langbot's master key; the record is bound to the bot and your account.
- It is decrypted only by the process that runs live bots, just before it signs a request to Kalshi.
- It is never returned by any API, never shown again and never written to a log.

## Bring your own code (coming soon)

Next, a hosted bot can be your own repo or script, in any language. It runs against a
Kalshi-compatible paper exchange that Langbot serves on live markets, so the same code that trades
on paper is the code you promote, with the same versions, rollback, guardrails and kill switch.
Free includes 1 small always-on code bot, Pro 5 and Team 25; extra always-on bots are $5 a month
each. This is in beta and not open to everyone yet.

## What results mean

Paper results are a simulation on live data; live results are what happened on your account.
Neither predicts what comes next, and most strategies lose money after fees. Langbot measures; it
does not give advice.