Run a Kalshi 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.

Use the public example repository and implement your own rule in strategy.mjs. The repository contains no HiveTrade production strategy, and its placeholder rule is not a recommendation. What your bot trades is your decision only.

Before you start

• Real Kalshi, real money. Your bot Hive places real orders in your real Kalshi account. HiveTrade never uses Kalshi's demo site, and a key created there does not work.
• You need your own Kalshi account, verified by Kalshi and funded. Funding, withdrawals and settlement all happen in Kalshi.

Setup

1. Follow the quick start to install the repository and generate the bot's signing key.
2. Register its public address at Create a bot Hive, choose Kalshi, and save the Hive ID. If an AI agent is setting the bot up, it prepares this page for you and reads the Hive ID back (how). New bot Hives are Private (how to make one public).
3. Create your Kalshi API key on kalshi.com.
4. Connect Kalshi in HiveTrade and press Allow copy-trading.
5. Choose your exact, currently open ticker (see below).

Create your Kalshi API key

You do this yourself, on kalshi.com. Your AI agent never needs to see the key.

1. Sign in at kalshi.com and open your account settings from your profile icon (top right), or go straight to kalshi.com/account/profile.
2. Find the API Keys section and press Create New API Key. Give it a name you will recognise, for example the bot's name. Either key type Kalshi offers works.
3. Choose Full access: read and write access for transactions, including trade and internal transfer. HiveTrade refuses a key without them when you connect. Permissions are fixed when the key is created: to change them, create a new key.
4. Kalshi shows a Key ID and a private key, and downloads the private key as a .txt file. Kalshi shows the private key only once, so keep that file.
5. Keep both private. You paste them only into HiveTrade Settings (next section), never into the bot's .env, the bot's files, or a chat with your AI agent.

With Full access the key can trade, and move collateral only between balances inside your own Kalshi account (Kalshi keeps cash for some market groups apart). It cannot withdraw.

Connect Kalshi in HiveTrade

1. Sign in at app.hivetrade.com, the same site where you created the bot Hive, and open Settings, then the Connections tab.
2. Under Exchanges, press Connect Kalshi. If it asks whether you have a Kalshi account, press I already have one.
3. Key ID: paste the Key ID from Kalshi.
4. Private key file: press Choose file and pick the .txt file Kalshi downloaded, or drop the file on the box. To paste it instead, press Paste it instead and paste the whole key, including the BEGIN and END lines.
5. If a risk notice appears, read it and tick it. Press Connect. HiveTrade checks the key's permissions now and tells you straight away if one is missing.
6. Tick I understand HiveTrade will place these orders automatically, and I accept the Kalshi Venue Schedule, then press Allow copy-trading.

Settings then shows Kalshi as Ready. Until you press Allow copy-trading, it shows Consent required and HiveTrade places no Kalshi order for you or your bot. You can disconnect the key in the same place at any time.

Configure .env

VENUE=kalshi
BOT_API_URL=https://api.hivetrade.com
BOT_HIVE_ID=<your-hive-id>
BOT_LIVE_TRADING_ENABLED=false
KALSHI_TICKER=<exact-open-ticker>
EXAMPLE_SIDE=
EXAMPLE_MAX_PRICE=

The page that confirms your new Hive shows these lines for your Hive: add them to your existing .env, don't replace the file, or you lose the signing key that npm run setup wrote. A test Hive on HiveTrade's dev site (dev.hivetrade.com) uses BOT_API_URL=https://api-dev.hivetrade.com instead.

Current public main reads no amount setting: it ignores a leftover KALSHI_CONTRACTS, STAKE_USD or MAX_STAKE_USD and warns you to remove it. Do not remove fields from a signed legacy request after signing it.

The bot's signing key and your Kalshi key are separate. The signing key stays in the bot's .env; the Kalshi Key ID and private key go only into HiveTrade Settings, never into this runner. No amount is configured in .env: each Call stakes the Hive's Amount per Call, within its Total budget, both set on the Hive when you create it and editable in Hive HQ. The amounts are yours to choose.

The repository ships a placeholder rule that reads EXAMPLE_SIDE and EXAMPLE_MAX_PRICE (prices from $0 to $1) only to show the interface. Your agent replaces it with the rule you describe before you enable live trading. The current starter can place real orders with that configured example rule.

Run npm start for a dry run. It reads public market data and prints SKIP or the proposed market, side and price cap; it submits no intent or order. The command checks once and exits.

Markets the bot API accepts

The API accepts a Kalshi bot Call for a market in any series below, whatever the Hive's category. Any other ticker is refused with KALSHI_BOT_TICKER_UNSUPPORTED. Current public main checks KALSHI_TICKER or KALSHI_SERIES against the same list and stops when it is not on it; an older copy runs only the three crypto 15-minute series (the first bullet below).

This list describes what the integration can execute; it is not a suggestion of what to trade.

15-minute markets change every 15 minutes. Each market in the crypto 15-minute series closes 15 minutes after it opens, and the next one has a new ticker. A fixed KALSHI_TICKER therefore stops working within 15 minutes, and the run stops with Stopped during public market lookup. Set KALSHI_SERIES to the market's series instead, with KALSHI_TICKER empty: each run then uses the market of that series that is open now. If several are open at once, the run lists them and stops; set KALSHI_TICKER to the one your rule trades and empty KALSHI_SERIES.

Prices. The price ceiling your bot signs is a whole-cent price from $0.01 to $0.99. Kalshi quotes some markets, including the 15-minute ones, in tenths of a cent below $0.10 and above $0.90 (for example $0.999); the signed ceiling is still a whole cent.

• Crypto, 15-minute up/down: KXBTC15M, KXETH15M, KXSOL15M
• Nasdaq-100, daily up/down: KXNASDAQDUD
• Esports match winners: KXCS2GAME, KXLOLGAME, KXVALORANTGAME, KXDOTA2GAME, KXR6GAME, KXCODGAME, KXOWGAME, KXRLGAME
• Soccer match results: KXEPLGAME, KXLALIGAGAME, KXSERIEAGAME, KXBUNDESLIGAGAME, KXLIGUE1GAME, KXUCLGAME, KXUELGAME, KXUECLGAME, KXEREDIVISIEGAME, KXLIGAPORTUGALGAME, KXEFLCHAMPIONSHIPGAME, KXSCOTTISHPREMGAME, KXBELGIANPLGAME, KXSUPERLIGGAME, KXCOPADELREYGAME, KXMLSGAME, KXLIGAMXGAME, KXARGPREMDIVGAME, KXDIMAYORGAME, KXCONMEBOLLIBGAME, KXCONMEBOLSUDGAME, KXSAUDIPLGAME, KXJLEAGUEGAME, KXFIFAWGAME
• Other sports game, match and fight winners: KXNFLGAME, KXNCAAFGAME, KXCFLGAME, KXNBAGAME, KXWNBAGAME, KXEUROLEAGUEGAME, KXNBLGAME, KXNHLGAME, KXKHLGAME, KXMLBGAME, KXKBOGAME, KXNPBGAME, KXATPMATCH, KXWTAMATCH, KXATPCHALLENGERMATCH, KXWTACHALLENGERMATCH, KXUFCFIGHT, KXODIMATCH, KXT20MATCH, KXTESTMATCH
• Elections and political events: KXHOUSERACE, KXSTATELEG, KXCAELECTION, KXSTATEBALLOTMEASURE, KXCAATTORNEYGENERAL, KXGOVAK, KXMISENATE, KXAKSENATE, KXIASENATE, KXMIDTERMHAPPEN, KXCHICAGOMAYOR, KXTORONTOMAYOR, KXVANCOUVERMAYOR, KXTAIPEIMAYOR, KXISRAELPM, KXBRPRES, KXFRENCHPRES, KXSPANISHPM, KXNEXTROMANIAPM, KXPRESNOMD, KXPRESNOMR, KXVPRESNOMD, KXVPRESNOMR, KXPRESPERSON, KXNOBELPEACE, KXUSAIRANAGREEMENT, KXIMPEACH, KXBILLS, KXELECTIONBILL, KXSCOTUSCASE, KXKASHOUT, KXALITOOUT, KXTRUMPADMINLEAVE, KXCABOUT, KXNEXTPRESSEC
• Economics: central-bank decisions, inflation, jobs, growth: KXFEDDECISION, KXFED, KXRATEHIKE, KXCBDECISIONEU, KXCBDECISIONENGLAND, KXCBDECISIONCANADA, KXCBDECISIONJAPAN, KXCPI, KXCPIYOY, KXCPICORE, KXCPICOREYOY, KXPCECORE, KXU3, KXPAYROLLS, KXGDP, KXRECSSNBER, KXMORTGAGERATE
• Entertainment awards and rankings: KXOSCARPIC, KXOSCARDIR, KXOSCARACTO, KXOSCARACTR, KXOSCARSUPACTO, KXOSCARSUPACTR, KXOSCARNOMPIC, KXCRITICSPIC, KXCRITICSDIR, KXCRITICSACTO, KXCRITICSACTR, KXCRITICSCHOICENOM, KXGGNOM, KXGRAMAOTY, KXGRAMBNA, KXGRAMMYNOMAOTY, KXGAMEAWARDS, KXTIME, KXSEXYMAN, KXDANCINGWITHTHESTARS, KXSUPERBOWLHEADLINE, KXBOND, KXTOPSONG, KXNETFLIXRANKMOVIE, KXNETFLIXRANKSHOW
• Weather, daily US-city highs: KXHIGHNY, KXHIGHCHI, KXHIGHLAX, KXHIGHMIA, KXHIGHAUS, KXHIGHDEN, KXHIGHPHIL, KXHIGHTATL, KXHIGHTBOS, KXHIGHTDAL, KXHIGHTDC, KXHIGHTHOU, KXHIGHTLV, KXHIGHTMIN, KXHIGHTOKC, KXHIGHTPHX, KXHIGHTSATX, KXHIGHTSEA, KXHIGHTSFO
• Weather, daily US-city lows: KXLOWTNYC, KXLOWTCHI, KXLOWTLAX, KXLOWTMIA, KXLOWTAUS, KXLOWTDEN, KXLOWTPHIL, KXLOWTATL, KXLOWTBOS, KXLOWTDAL, KXLOWTDC, KXLOWTLV, KXLOWTMIN, KXLOWTNOLA, KXLOWTOKC, KXLOWTPHX, KXLOWTSATX, KXLOWTSEA, KXLOWTSFO
• Weather, daily rain: KXRAIN
• Economics, weekly TSA checkpoint screenings: KXTSAW
• Commodities, daily settle (gold, silver, natural gas, Brent, copper): KXGOLDD, KXSILVERD, KXNATGASD, KXBRENTD, KXCOPPERD
• Mention markets: KXTRUMPMENTION, KXTRUMPMENTIONB, KXTRUMPSAY, KXTRUMPSAYMONTH, KXTRUMPSAYCOMPANY, KXTRUMPSAYCOUNTRY, KXTRUMPSAYNICKNAME, KXVANCEMENTION, KXSECPRESSMENTION, KXFEDMENTION, KXDEBATEMENTION, KXBURNHAMMENTION

A series is added only after a review, so this list changes over time.

Costs and sizes

• A Call names no amount. HiveTrade sizes the Captain order from the Hive's Amount per Call: the most contracts, in steps of 0.01, whose cost plus Kalshi's fee fit it at the Call's price ceiling. The smallest order is 0.01 contract.
• Kalshi's taker fee is 0.07 × m × contracts × price × (1 − price), rounded up to the next cent, where m is the fee multiplier Kalshi sets for the market's series (1 on most series; MLB games use 0.5 until the first pitch). HiveTrade reads m for the market when the Call arrives (a game about to start already counts at the full fee).
• An older bot that still signs a contract count and a stake keeps its signed format, but the API ignores those amounts when sizing the Captain leg. It uses the Hive's Amount per Call. A lower locally printed stake or MAX_STAKE_USD does not lower that amount; verify the Hive settings separately.
• A contract pays $1 if its side wins and $0 if it loses: a position can lose its entire cost.

Execution and verification

Current public main signs a kalshi-v2 intent with execution: "hivetrade-v1", exact ticker, side and price ceiling, and no amount. An older copy also signs the stake and a whole contract count; the API accepts both signed shapes. HiveTrade executes through your connected account and returns the Captain outcome. The runner must not place a second Kalshi order or post a Polymarket fill report.

The old kalshi-v1 signal and Kalshi fill-report flow is retired: the API refuses both. Upgrade old runners to the public example's v2 flow; a refusal is not permission to send a local order. You connect one Kalshi key in Settings, not a separate verification key. It needs Full access (above); it cannot withdraw.

As the operator, your bot's Captain trades already use your connected Kalshi account. Backing that same Hive does not create a second copy. Current releases also prevent creating or increasing that backing; pausing or stopping an old backing remains possible.

Set BOT_LIVE_TRADING_ENABLED=true only when you intend to place real orders. Verify both the Hive Call and actual venue fill. An accepted request is not proof of a fill; an uncertain response stops for reconciliation. Keep the journal.

Funding, withdrawals and settlement happen in Kalshi. There is no Polygon wallet, wrapping or on-chain redemption in this path. Verification and recovery.