Build a custom bot

Installed the starter before 2 November 2026?

Update it to the current main of hive-trade/bots before any live run. Older copies place Polymarket orders from a bot wallet of their own and sign their own stake, and their Kalshi rule accepts only three crypto series. The current starter only signs the Call: HiveTrade places the order in your own HiveTrade account, and each Call stakes the Hive's Amount per Call within its Total budget. Never work around an API refusal by placing a local order.

The public example repository gives your AI coding agent a standalone starting point. It includes setup tools, a placeholder rule that only shows the interface, and the public signing/execution integration for both venues. HiveTrade's production strategies, tuning and private code are not included. HiveTrade provides tools, never financial advice or what to trade: your agent implements the rule you describe and does not propose one.

The starter deliberately attempts each configured market once and keeps a persistent journal. Hive HQ's six-hour buy-window selection is not exposed by this example. A Hive cannot open a second Call on the same exchange market while its existing Call is unresolved and has not been closed by the Captain; stopping buying alone does not free that slot. A declined or uncertain intent must not trigger a fallback local order; keep the journal and reconcile.

Give this to your agent

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, the exact
   market (a link or its name), my own trading rule in my own words, the Amount
   per Call (what each Call stakes) and the Total budget for my Hive, and whether
   it should run on this computer or on a server.
3. Tell me the command that creates my bot's signing key. I'll run it myself
   and give you only the public address. Never read or open the file that
   holds 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.

New to this? Set up in one prompt explains what you need and what happens next.

Install as a Claude Code plugin

In Claude Code, add the example repository as a plugin source and install the bot plugin. It bundles the setup and hosting skills plus a local MCP server:

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

What your agent does and what only you do: Set up with your AI agent. The MCP server runs on your computer, next to your bot's files. It can prepare the pre-filled Create a bot Hive link, read your Hive ID back once you press Create, and run a dry run. It never reads your private key into the conversation, never places a live order, and never holds an account login. Other MCP clients can start it with node mcp/server.mjs from the repository.

Quick start

Install Node.js 24 or newer, then:

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

Setup saves the private key in a local .env and prints only its public address. Register that address at Create a bot Hive. Choose the venue and save the returned Hive ID in .env.

Complete Polymarket wallet setup or Kalshi account setup. Configure your exact market and your rule, keep BOT_LIVE_TRADING_ENABLED=false, and run npm start. The example rule skips until you set its side and price cap. Replace it with your own rule before enabling live trading: the current starter can place real orders with the configured example rule.

Polymarket execution modes

A new Polymarket bot only signs its Call: the market, the side and the highest price it accepts. A Call carries no amount: it stakes the Hive's Amount per Call, within its Total budget, both set on the Hive. HiveTrade checks the Call against its own available Total budget and the account cash available to it after accounting for your other Member and Captain budgets, then places the Captain order in your own HiveTrade account and the Members' copies in theirs. The bot places no order, holds no money and reports no fill. To leave a position early it signs an exit, and HiveTrade sells the Captain position and the Members' copies.

Bots created before this setup trade from their own wallet with an older protocol. A Hive that HiveTrade has moved to the new setup refuses that older protocol with PM_CAPTAIN_EXECUTED_BY_HIVETRADE: stop and check that your installed client supports pm-op-v1. Current public main supports it, so update an older copy. Do not bypass the refusal or place a local fallback order.

Kalshi remains API-owned execution through the connected account. A Kalshi Call names the ticker, the side and the highest price; HiveTrade sizes it from the Hive's Amount per Call in 0.01-contract steps, Kalshi's fee included. The public example never holds the Kalshi venue key. See the Kalshi guide.

Copy budgets

The current starter uses each Member's own per-call budget for copying, subject to tier, remaining-budget and execution limits. Your Hive's Amount per Call does not set a Member's copy size. Remove a leftover SIGNAL_STRENGTH setting; the starter ignores it. Older signed clients remain compatible, but sending a lower level does not reduce Member copies. See copy sizing.

Position disclosure

Each Call shows Members the Captain's position in that market, in words: "I hold a position in this market", "I intend to take a position in this market" or "No position". A signal may state it with positionDisclosure set to holds, intends or none. When set, sign it as a position:<value> line directly before the nonce: line; when omitted, sign no such line.

It is optional and no signal is refused without it. When you omit it, HiveTrade shows holds if your signal reported a filled order, intends if an order is going in with the Call, and nothing otherwise. Your Captain Terms still apply: if your bot holds a position HiveTrade cannot see, say so with holds. A signed none is replaced by intends when an order is going in with the Call.

What the current main example does

• Checks one market per invocation and exits.
• Ships a placeholder rule (a side and maximum price you type in) that only shows the interface; it is not a recommendation.
• Prints SKIP or a proposed signal with its market, side and price cap. It signs no amount: each Call stakes the Hive's Amount per Call. Your rule can return reasons, short lines the dry run prints as TRACE lines.
• On Polymarket, checks before each live run that the Hive trades from your own HiveTrade account, then signs a pm-op-v1 Call. HiveTrade places the order; the runner places none and reports no fill. Older bots keep their own-wallet flow behind a marked legacy setting.
• Uses Kalshi's signed v2 intent; HiveTrade executes via the connected account.
• Keeps a persistent journal to stop duplicate or uncertain live attempts.

The runner does not manage exits, wrapping, redemption or a portfolio. Your agent can extend it with your own data and rules, keeping the execution guards intact. On Kalshi, only the series the bot API accepts pass its gate.

See the repository's public protocol guide and recovery guide. Tests and a dry run do not prove a funded live trade will succeed. Enable real orders only when you intend to trade, then verify the venue receipt and Hive Call.