# Build your own HiveTrade bot

Give this repository to your AI coding agent. It contains an educational example,
setup tools, and the public integration code needed to publish Calls from **your
own strategy**. HiveTrade's production strategies and their tuning are not included.

HiveTrade is signal-sharing software for Polymarket and Kalshi. Trades execute in
participants' own venue accounts. Trading fees apply.

## Paste this into your agent

New to this? Use an AI agent that can run commands on your computer (Claude Code,
Codex, Cursor). Step-by-step for beginners: https://docs.hivetrade.com/run-a-bot/one-prompt

```text
Set up my own HiveTrade bot using https://github.com/hive-trade/bots.
I'm new to this, so explain each step in plain words.
1. Clone the repository into a new folder, then read README.md and AGENTS.md.
2. Ask me a few questions: Polymarket or Kalshi, my bot's name, my own trading
   rule in my own words, the exact market it trades (a link is fine), the
   Amount per Call (what each Call stakes) and the Total budget for the Hive,
   and whether it should run on this computer or on a server.
3. Tell me the command that creates the bot's signing key. I will run it myself
   and give you only the public address it prints. Never run it yourself, never
   open .env, and never ask me for the private key.
4. Implement exactly my rule, run the tests, and show me a dry run with its
   decision trace. Do not suggest, rank or improve strategies or markets:
   choosing what to trade is my decision.
5. Give me a pre-filled "Create a bot Hive" link. I will check the signing
   address and press Create myself.
6. Find my new Hive, then tell me exactly which steps I still have to do myself.
Never turn on real trading unless I clearly ask you to.
```

Using Claude Code? Install the plugin below and ask it to "set up my HiveTrade bot".

## Install as a Claude Code plugin

```text
/plugin marketplace add hive-trade/bots
/plugin install hivetrade-bot@hivetrade
```

The plugin adds the guided setup skill and a local MCP server (`hivetrade-bot`)
that works on the bot in your current project folder. Clone this repository there
first (step 1). On the first session the plugin installs its dependencies, which
can take about a minute; if the server shows as failed in `/mcp`, reconnect it.
The server never returns your private key, never posts a Call, and has no way to
enable live trading, move funds or read an account credential.

**Other MCP clients:** run `node mcp/server.mjs` from your clone (after `npm ci`)
as a stdio server. It uses the current directory, or `HIVETRADE_BOT_DIR` if set.
In Claude Code without the plugin: `claude mcp add hivetrade-bot -- node mcp/server.mjs`.

## How setup works

1. **You:** run `npm run setup` in your own terminal, in the bot folder. It saves
   the bot's signing key in `.env` and prints only its public address. Give that
   address to your agent. Your agent never runs this command and never opens `.env`.
2. **Agent:** writes your strategy, runs the tests and a dry run.
3. **Agent:** prepares a pre-filled "Create a bot Hive" link.
4. **You:** open it, check the signing address, and press **Create bot Hive**.
5. **Agent:** reads the new Hive ID back with a request signed by the bot's key.
6. **You:** on the Hive, set its **Amount per Call** (what each Call stakes) and
   its **Total budget**, when you create it or later in Studio. Kalshi: connect
   your Kalshi API key and consent. Polymarket: allow the bot to trade (in
   Studio, or while you create the Hive). The bot trades from your own HiveTrade
   account, so that account holds the money, not the bot.
7. **You:** turn on live trading, only when you decide to.

Details, the tool reference and troubleshooting: [Set up with an AI agent](docs/agent-setup.md).

## What you get

- A small **user-selected side + maximum price** example, disabled until configured.
  It is a programming example, not a forecast or a promise of profit.
- A Call carries no amount. The bot sends the market, the side and a price cap;
  each Call stakes the Amount per Call set on the Hive, within its Total budget.
- Polymarket: the bot signs the Call and HiveTrade places the order in your own
  HiveTrade account.
  No wallet, no order code and no Polymarket credentials in this runner. Older
  bots that place their own orders use a clearly marked legacy setting.
- Kalshi: signed v2 intent; HiveTrade executes using the operator's connected account.
  No Kalshi private key belongs in this runner.
- Local key creation, spending checks, persistent duplicate prevention,
  and tests that do not place real trades.

The runner checks **one exact market once, then exits**. Start here before adding
market discovery or a timed loop. It does not manage exits, wrapping, redemption,
or a portfolio. Polymarket positions sit in your own HiveTrade account and
settle there; Kalshi handles settlement in your Kalshi account.

## 1. Install and create an identity

Requires Node.js 24+ and npm. Clone the **whole repository**, not a single script:

Your agent can do the first part:

```bash
git clone https://github.com/hive-trade/bots.git my-bot
cd my-bot
npm ci
npm run check
npm test
```

`npm ci` may report a few **low** severity advisories. They come from the
Polymarket SDK's older cryptography library and have no fix yet; you do not need
to run `npm audit fix --force`, which can break the SDK.

**You** create the signing key, in your own terminal, in that folder:

```bash
npm run setup            # production (app.hivetrade.com)
npm run setup -- --dev   # or the dev site (dev.hivetrade.com, still real money)
```

It prints two lines:

```text
Your bot's public address: 0x...
Give this address to your agent. Your private key was saved in .env; never share it.
```

`setup` creates `.env` with permissions `0600`, never shows the key and refuses to
overwrite an existing `.env`. Your agent never runs `setup` and never reads, prints
or opens `.env`. It changes public settings with `npm run settings -- KEY=value`
(or the MCP tool `update_settings`) and views them with `npm run settings`, which
hides the key. Keep a private backup of the identity;
losing it may lose access to the associated wallet. Never commit `.env`, journal
files, or credentials. The example needs no access to HiveTrade's private repository.

## 2. Register the Hive

Only you can create the Hive, in your own signed-in browser. Your agent builds a
pre-filled link (MCP tool `prepare_registration`) and never submits it. Open it,
check that the **signing address** is exactly the one your agent showed you, and
press **Create bot Hive**. The agent then reads the Hive
ID back (`check_registration`) or, if that lookup is not available yet, asks you
for the ID the page showed and saves it with `set_hive_id`. You can also save it
yourself: `npm run set-hive -- 4262` (with your Hive's ID).

`npm run whoami` asks HiveTrade, signed with the bot's key, which Hive the key
belongs to and whether `BOT_HIVE_ID` in `.env` matches. It prints only public
facts and changes nothing.

**The Hive page shows a short `.env` snippet** (`VENUE`, `BOT_HIVE_ID`,
`BOT_API_URL`). Never paste it over your `.env` file: that deletes the bot's
signing key. Use `npm run set-hive -- <ID>` and `npm run settings -- KEY=value`
instead. See [agent setup](docs/agent-setup.md).

Manual fallback: sign in at Create a bot Hive
([production](https://app.hivetrade.com/bots/new) or [dev](https://dev.hivetrade.com/bots/new)),
choose the venue, name the Hive, enter the **public signing address**, and give
your agent the Hive ID the page shows (it saves it with `set_hive_id`), or run
`npm run set-hive -- <ID>` yourself.

**Amount per Call and Total budget.** Both are set on the Hive, in HiveTrade:
when you create it (the pre-filled link fills in the Amount per Call; you type
the Total budget) and at any time later in Studio. Neither lives in `.env`, and
the bot sends no amount with its Calls.

- **Amount per Call** is what each Call stakes, the same way a Member's per-Call
  budget sizes their copy. The order is still capped at your strategy's price
  cap and the Call's price band, and it can fill partly or not at all.
- **Total budget** is the most the bot can have at risk: live stakes plus losses
  since you set it count as used, and wins refill it up to the total. When less
  than the Amount per Call is left, the Call stakes what is left if that still
  meets the exchange minimum, and is skipped otherwise.

There is no daily limit: a run places at most one order on its market, and the
kit never trades the same market twice. Older settings (`STAKE_USD`,
`MAX_STAKE_USD`, `KALSHI_CONTRACTS`) are ignored, with a warning, except by a
legacy Polymarket bot (below).

**How Members' copies are sized.** Each Member's copy of your Call is their own
per-call budget, in full, reduced only by their tier cap, what is left in their
Hive budget, and what the market can fill inside the Call's price limit. Your
Hive's Amount per Call does not set it.

### Environments

| | Web (where you create the Hive) | API (`BOT_API_URL`) |
|---|---|---|
| Production (default) | `https://app.hivetrade.com` | `https://api.hivetrade.com` |
| Dev | `https://dev.hivetrade.com` | `https://api-dev.hivetrade.com` |

**Dev is not play money.** The dev site places real orders with real funds on
Polymarket and Kalshi, exactly like production. Use small amounts on both.

A Hive exists on one environment only. Never mix them: the web site where you
press Create and the bot's `BOT_API_URL` must be on the same row. An API rejection is a
failed preflight, not permission to bypass a restriction.

## 3. Complete venue setup

### Kalshi

1. Set `VENUE=kalshi`.
2. Have an eligible, funded Kalshi account. Connect your Kalshi API key in
   HiveTrade Settings and complete the required execution consent.
3. Choose the market. HiveTrade's bot API accepts markets in about 190 Kalshi
   series (crypto, sports, elections, economics, weather and more), listed at
   [Markets the bot API accepts](https://docs.hivetrade.com/run-a-bot/kalshi);
   the kit carries the same list in `lib/kalshi-markets.mjs`. Then set one of:
   - `KALSHI_TICKER`: one exact open market. It trades that market only, and
     stops with "has closed" once the market closes.
   - `KALSHI_SERIES` (for example `KXBTC15M`): each run uses the market of that
     series that is open right now. Useful for 15-minute series, whose markets
     close every 15 minutes. If several markets of the series are open at once,
     it lists them and you set `KALSHI_TICKER` to the one your rule trades.
4. Each Call stakes the Hive's Amount per Call: HiveTrade buys the most
   hundredths of a contract whose cost plus Kalshi's fee fit it, at most at your
   strategy's price cap. There is no contract count to set.

**Your Kalshi API key** goes into HiveTrade, never into this kit. On kalshi.com
(labels as seen on 2026-10-25): profile icon, **Account & security**, **API keys**,
**Create new API key**. Tick **Trade** and **Transfer between your Kalshi
portfolios**; leave **Withdraw** unticked, so the key cannot take money out.
Kalshi shows a Key ID and downloads the private key as a file, once. In
HiveTrade, open Settings, choose **Connect Kalshi**, enter the Key ID and the key
file, accept the consent and allow copy-trading. Only you do this, in your own
browser; your agent never sees that key.

Only the bot's signing key goes in `.env`. HiveTrade submits the Captain order;
do not add a second local Kalshi order or a Polymarket-style fill report.

### Polymarket

**Event link or market slug?** A Polymarket *event* page
(`polymarket.com/event/<event>`) can hold many Yes/No *markets*, and each market
has its own slug. The bot trades exactly one market, so `MARKET_SLUG` must be a
market slug. Paste the link into `npm run find-market -- <link>` (MCP tool
`find_market`): if the link points at one market it prints `MARKET_SLUG=...`, its
status and Polymarket's end date; if it is an event, it lists the event's open
markets and you pick the one your rule trades.

1. Set `VENUE=polymarket` and an exact binary Yes/No `MARKET_SLUG` (a
   polymarket.com link is not a slug: `npm run find-market -- <link>` turns it
   into one). You can create the Hive and run dry runs today.
2. **The bot trades from your own HiveTrade account.** The bot signs the Call
   (the side, and your strategy's `maxPrice` as the price cap; no amount) and
   HiveTrade places the order in your account, exactly like a Call you place
   yourself, staking the Hive's **Amount per Call** within its **Total budget**.
   In HiveTrade, set both amounts and **allow the bot to trade** (in Studio, or
   while you create the Hive). Budgets your Members set aside are never touched. There is nothing to fund for the bot itself: never send
   money to the bot's signing address, never sign in to Polymarket as the bot,
   and never import the bot's key into a wallet app.
3. Before each live run the bot checks, with a request signed by its key, that
   its Hive trades from your account. If it does not yet, it stops and says so.

**Older Polymarket bots (legacy).** A bot created before this change may still
place its own order from a deposit wallet its operator set up. Only such a bot
sets `POLYMARKET_LEGACY_SELF_MANAGED=true` and `POLYMARKET_DEPOSIT_WALLET`, and
still signs its own `STAKE_USD` (at most `MAX_STAKE_USD` and the Hive's Amount
per Call), because it buys from its own wallet
(**register the wallet**: `npm run bind-wallet`, same as
`npm run register-wallet`; see [the protocol](docs/protocol.md)). This path
goes away once every older bot has moved to your HiveTrade account; new bots
never use it. Follow the venue's eligibility rules; a server does not change
regional eligibility.

## 4. Implement your idea and preview it

Your agent should edit `strategy.mjs`. It receives a market with `question`,
`yesAsk` and `noAsk`, and returns either a skip (`null` or
`{ skip: true, reasons }`) or a trade (`{ side: "yes" | "no", maxPrice, reasons }`).
Prices are decimal probabilities: `0.40` means 40 cents. `maxPrice` is the highest
price the order may pay, and that price itself is allowed. `reasons` is optional:
a list of short text lines that the dry run prints as `TRACE` lines, so you can
see why your rule did or did not trade. The dry run also prints the market and
its asks as `TRACE` lines before your rule's own.

To try the illustrative rule, set `EXAMPLE_SIDE` and `EXAMPLE_MAX_PRICE`. Without
both, it skips or rejects configuration. This rule only demonstrates a price
limit: it has no predictive edge. Match any real data source to the market's
resolution rules. See [example ideas](strategy-playbook.md).

**Tests.** The example rule's tests are in `test/example-strategy.test.mjs`.
When you replace `strategy.mjs`, replace that file with tests for your own rule.
The other files in `test/` check the kit itself and never load `strategy.mjs`,
so they stay green whatever your rule is.

Preview it with a dry run:

```bash
npm run dry-run
```

`npm run dry-run` always runs with live trading off and without the signing key,
whatever `.env` says. It needs no Hive ID, so you can run it before you create
the Hive. (`npm start` does the same while `BOT_LIVE_TRADING_ENABLED=false`.)
A dry run fetches public market data and prints a decision. It submits **no intent,
order, or fill report**. It does not prove wallet funding, trading permissions, or
that a live order will fill.

## 5. Enable only when you intend to trade

Review the exact market, side, price cap, strategy, venue account, and the
Hive's Amount per Call and Total budget in Studio.
Set `BOT_LIVE_TRADING_ENABLED=true` locally and run `npm start` once. This can
place real orders and trigger follower copies. Check the venue receipt and Hive
Call together before considering the integration verified.

A successful API response alone is not proof of a fill. An uncertain result stops
the runner and leaves a journal entry for reconciliation. There are no automatic
order retries. See [recovery](docs/recovery.md) before restarting after a failure.

## Hosting and extending

**Today the guided server setup runs practice only.** The Railway helper
([guide](docs/railway.md), skill
[`skills/hivetrade-deploy/SKILL.md`](skills/hivetrade-deploy/SKILL.md)) deploys
scheduled **dry runs**: the server checks your market on a timer, with live
trading always off and no signing key. It cannot place real orders, even if you
change a setting on the server. Real trading works only on your own computer
today (step 5). Your decision trace (`TRACE` lines) shows only in local runs; the
server prints a short completion line instead, so your strategy's output never
reaches a host's logs.

Local execution stops when the computer sleeps or the process exits. Review the
host's current pricing before deploying: a server costs money even for practice.
`npm run railway -- plan <config>.json` checks a config before you have a Railway
project; `deploy` and `verify` then need the three Railway UUIDs. Keep your
strategy in a repository you control and choose its visibility deliberately.

Building your own live server setup is outside what this kit guides. If you do,
`railway.json` starts `node bot.mjs` from the host's environment variables and
disables automatic restarts (an uncertain trade must be reconciled, not
restarted in a loop). Use one runner instance and a persistent volume for
`STATE_DIR`: an empty new volume loses duplicate protection. You put the private
key in the host's secret settings yourself, never in a Dockerfile or Git
repository; your agent never copies it.

The runner is a one-shot job, not a web service: it has no `/health` endpoint
and will not trade the same market twice. For a continuous bot, your agent must
add market selection, fresh data, exposure and cumulative spending limits,
supervision, exit/settlement handling, and tests. Do not remove the execution
guards to make it run.

## Documentation and support

- [Public setup docs](https://docs.hivetrade.com/run-a-bot/custom)
- [HiveTrade docs: set up with your AI agent](https://docs.hivetrade.com/run-a-bot/agent)
- [Set up with an AI agent](docs/agent-setup.md)
- [Wire contract](docs/protocol.md)
- [Recovery and verification](docs/recovery.md)

Compatibility checked against HiveTrade's current API contract on 2026-09-15.
Offline tests and dry runs do not certify a funded live account. Report an issue
with redacted configuration and an error stage; never attach keys or full SDK logs.