Jev Kalshi Bitcoin Bot: build prompt
Build your own AI trading bot for Kalshi's 15-minute Bitcoin markets with one prompt. Paste the prompt below into Claude Code or Codex in an empty folder. Your coding agent asks you a few questions first (your strategy, your limits, your time zone and take-profit), then builds and tests the bot with you.
What it builds: every 15 minutes, 5 minutes into the window, the bot takes one snapshot of Kalshi's "BTC price up in next 15 mins?" market (series KXBTC15M). Code does the maths and turns it into a few short facts in plain words. Jev, TypeSafe AI's decision model, reads them and answers in about a third of a second: UP, DOWN or SKIP, plus its own odds. Code places at most one immediate-or-cancel order, only when Jev is confident and its odds beat Kalshi's price. After a buy, the bot watches the trade every 5 seconds. When buyers pay 95¢ or more, Jev decides whether to take the profit early. Predictefy supplies the live Bitcoin price, Kalshi's order book and the Kalshi trading client, which signs every order on your own PC. Hard limits are enforced in code, not by the AI.
You need:
- A verified, funded Kalshi account, with your money moved to the Crypto exchange shard (Account, then Exchange indexes). Money on the Default shard can't be used in crypto markets.
- A Kalshi API key with Read all data and Trade (leave Transfers off), and its private key file.
- A Predictefy API key. The bot uses about 3,400 credits a day running around the clock. Take-profit adds none: it reads Kalshi's free public order book.
- A TypeSafe API key for Jev (console.typesafe.ai, then Keys), with credit added under Settings, then Billing. Jev costs $0.042 per million input tokens and output is free: about a third of a cent a day for the calls, plus at most about 12¢ a day for the take-profit checks. Access may be limited, so check the console first.
- Node.js 24 or newer, and a computer that stays on while the bot trades.
It trades real money. Start with the dry run (npm run bot), keep the stakes small, and watch what your bot does before you let it trade. This is an experiment, not financial advice.
The prompt (copy everything in the box)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 | You're going to build me a trading bot for Kalshi's 15-minute Bitcoin up/down markets (series KXBTC15M). It trades real money. Jev, TypeSafe AI's decision model, makes one call per 15-minute window. Code does all the maths, enforces every limit and places the orders. Predictefy supplies the live data and the Kalshi trading client. Kalshi is the exchange.
STEP 0: INTERVIEW ME FIRST
Before you write any code, ask me these questions one at a time. Each one has a default in brackets. If I say "default", use it.
1. My strategy, in plain English.
[Default: one snapshot 5 minutes into each window. Jev calls UP, DOWN or SKIP and gives its own odds. Trade only when Jev's confidence is at least 0.6 and its own odds for that side beat Kalshi's price plus the fee by at least 3 cents. Skipping is free and usually right.]
Also offer me these examples:
- Skip the windows around big scheduled US news (8:30 AM ET data releases, 2:00 PM ET Fed decisions).
- Only trade between 9:30 AM and 4 PM US Eastern.
- Never pay more than 90 cents a contract.
- Raise Jev's confidence bar to 0.7.
2. My limits.
[Default: a $10 budget of its own, tracked in its own ledger rather than the Kalshi total. Stake $1, or $2 when Jev's confidence is 0.8 or more, in whole contracts. At most one trade per window. Stop for the day after losing $3. Stop for good when the ledger reaches $4.]
3. My time zone, so the daily loss limit resets at my midnight. [No default: ask me.]
4. Take-profit.
[Default: on. After a buy, check the trade every 5 seconds until 1 minute before the close. Once a buyer pays 95 cents or more for my contracts and selling would be a profit after fees, ask Jev whether to sell now or hold. Sell only if Jev leans SELL at 60% or more on 2 checks in a row. Never sell at a loss.]
5. My setup: my operating system, my Node version (it must be 24 or newer), and where my .env file and Kalshi private key file will live (outside the project folder).
If my strategy is unclear, needs data this bot doesn't have (for example news or other exchanges), or conflicts with my limits, tell me and ask before you build. Then summarize my answers in one short list and wait for my OK.
STEP 1: WHAT TO BUILD
Ground rules
- Node 24 or newer, TypeScript run directly by Node (type stripping, so no enums or parameter properties). One dependency: @predictefy/sdk, pinned to 1.0.0-beta.9. Call TypeSafe's HTTP API with fetch; no SDK needed.
- Dry run by default. Live trading needs a --live flag and me typing LIVE at a prompt. You never run --live yourself, and you never place an order yourself.
- Keys live in a .env file outside the repo: PREDICTEFY_API_KEY, KALSHI_API_KEY_ID, KALSHI_PRIVATE_KEY_PATH (the path to the Kalshi private key file) and TYPESAFE_API_KEY. Read it with parseEnv from node:util. Never copy it into process.env, never log a key, and never print the key file.
- Write a failing test before each module (node --test), then make it pass.
- The bot never moves money between accounts or shards.
The market
- A new market opens every 15 minutes. UP (YES) wins if the 60-second average of CF Benchmarks' BRTI before close is at least the target (floor_strike), which is the 60-second average before open. Winners pay $1.00 per contract.
- Kalshi's free public API: GET https://api.elections.kalshi.com/trade-api/v2/markets?series_ticker=KXBTC15M&status=open lists the open window, its target (floor_strike) and its exchange_index. A new market can take about 20 seconds to appear after it opens. GET /markets/{ticker} gives result "yes" or "no" a few minutes after close.
- Taker fee: 0.07 x contracts x price x (1 - price), and the order's total is rounded up to the cent. Price steps are 0.01 between 0.10 and 0.90, and 0.001 outside that range.
Kalshi's Crypto shard
- Kalshi runs crypto markets on their own matching engine, exchange index 2 (Crypto). An order can only use money that's already on that shard. Otherwise Kalshi rejects it with "insufficient shard balance".
- Tell me to move my balance to Crypto (index 2) under Account, then Exchange indexes, on kalshi.com before going live.
- Before each live order, read that shard's balance (Get Balance's balance_breakdown for the market's exchange_index). If it can't cover the order's worst case, skip the window with a message that says so.
Kalshi host
- Create the client with new Predictefy({ apiKey, venueFetch, venueCredentials: { kalshi: { apiKeyId, privateKeyPem } } }). venueFetch rewrites https://external-api.kalshi.com to https://api.elections.kalshi.com, Kalshi's shared production host. The SDK's constructor ignores kalshiBaseUrl, and Kalshi signs only the path, so signatures stay valid.
- Prove the key with a read-only balance call before anything else.
Data
- BTC: client.watchFeedTicker({ feed: 'binance', symbol: 'BTC/USDT' }, onTicker, { onError, onClose }) into a price buffer. Reopen the stream if no price arrives for 30 seconds, and back off reconnects from 3 seconds to 60.
- Warm-up: client.feeds.fetchOHLCV({ feed: 'binance', symbol: 'BTC/USDT', timeframe: '1m', since: <ms one hour ago>, limit: 60 }). 1m is the finest timeframe. Add each closed candle's open at its open time and its close at open time + 59.999 s.
- Order book at the call: client.kalshi.fetchOrderBook(ticker) returns YES bids and asks (5 Predictefy credits). The NO ask is 1 minus the best YES bid.
- Order book during a trade: Kalshi's free public GET /markets/{ticker}/orderbook (no key, no credits). It lists buyers only: orderbook_fp.yes_dollars are YES bids and orderbook_fp.no_dollars are NO bids, each [price, size] as strings, cheapest first. A NO bid at p is a YES ask at 1 - p. Predictefy's order-book stream doesn't serve these 15-minute Kalshi markets.
Math model (a baseline, not the decision)
- x = BTC now minus Binance's own 60-second average before open. Without that history, fall back to the target.
- sigma = square root of (sum of squared price moves / elapsed seconds) over the last 30 minutes, at least $2 per square-root second.
- variance = sigma^2 x (seconds left - 60) + sigma^2 x 60 / 3, and P(UP) = normal CDF of x / sqrt(variance). One "typical move" for the time left is sqrt(variance).
What Jev reads at the call
Jev reads numbers as text and can't reliably compare them, and unrelated fields make it less accurate (TypeSafe's own docs say both). So code does every calculation and comparison first, and Jev gets one JSON object of short, named fields in plain words. No account details, no limits and no past calls. Build exactly these nine fields:
- market: Kalshi's "BTC price up in next 15 mins?" market for <open>-<close> ET. UP wins if BTC's 60-second average just before <close> ET is at or above the target set at the open; otherwise DOWN wins. The winning side pays $1 per contract.
- time_left: for example "10 minutes left of 15".
- btc_vs_target: "BTC is $60 above the target, about 0.8 typical moves for the time left", or "BTC is right at the target" when within 50 cents.
- btc_position: from z = x / typical move: under 0.25 "about level with the target"; under 0.75 "slightly above/below the target"; under 1.5 "clearly above/below"; otherwise "far above/below".
- momentum_last_minute and momentum_last_3_minutes: the move divided by sigma x sqrt(60 or 180 seconds). Under 0.5 is "flat (up $5)"; under 1.5 is "moderate rise (up $18)" or "moderate fall"; otherwise "strong rise" or "strong fall". Say "not enough price history yet" when missing.
- math_model: "The math model gives UP a 74% chance and DOWN 26%." Use "over 99%" and "under 1%" at the extremes.
- kalshi_prices: "UP costs 62¢ and DOWN costs 40¢ per contract, plus a fee of 2¢ on UP and 2¢ on DOWN. These prices imply a 61% chance of UP." (the fee is for one contract; the implied chance is the YES bid/ask midpoint). Say "No one is selling UP right now" when a side has no offer.
- value_by_math_model: for each side, the model's chance minus its price minus its fee: over +2 cents is "UP looks underpriced by 10¢ after the fee", under -2 cents is "overpriced by ...", otherwise "about fairly priced after the fee", or "UP can't be bought right now".
The Jev request
- POST https://api.typesafe.ai/v1/systemone with Authorization: Bearer <TYPESAFE_API_KEY> and a JSON body { state, model, questions }. Pin model "jev-1.13.0" (not jev-latest), so the answers behind the thresholds can't change under the bot.
- Two questions in one request, answered in parallel:
call: type "choice". Instructions: "Decide this window's trade. Buying a side costs its price plus the fee and pays $1 per contract if that side wins, $0 if it loses. Buy a side only when it is likely enough to win to be worth that cost. Skipping costs nothing." Criteria: UP: "Buy UP: BTC is likely to finish at or above the target, and UP is worth its price plus the fee." DOWN: "Buy DOWN: BTC is likely to finish below the target, and DOWN is worth its price plus the fee." SKIP: "No trade: neither side is clearly worth its price plus the fee, or the signals disagree."
up_wins: type "noul". Instructions: "BTC's 60-second average just before this window closes will be at or above the target, so UP wins." Criteria true: "UP wins: BTC finishes at or above the target." false: "DOWN wins: BTC finishes below the target."
- The answer arrives as answers.call.choice, answers.call.probabilities, answers.call.confidence (0 to 1) and answers.up_wins.noul (the probability UP wins). Reject anything outside the declared options.
- Errors skip the window with a plain reason and never crash the bot: 401 bad key, 402 out of credit (include the top-up link, console.typesafe.ai/settings/billing), 422 bad request, 429 or 529 busy (retry once after a second), network errors, and a 15-second deadline.
Code's rules at the call
- Trade only if Jev picks UP or DOWN, its confidence is at least 0.6, and Jev's own odds for that side (up_wins for UP, 1 - up_wins for DOWN) are at least the side's ask plus the one-contract fee plus 3 cents.
- Price cap = the lowest of 0.99, the ask plus 2 cents, and Jev's odds minus 3 cents minus the fee.
- Stake = $2 when Jev's confidence is 0.8 or more, otherwise $1, in whole contracts.
- Then the usual limits: one trade per window; stop for the day at the daily loss limit (open trades count at their worst case, and the day resets at my midnight); stop for good at the floor, and refuse any trade whose worst case would go below it; the answer must arrive within 15 seconds of the snapshot; the BTC price must be under 5 seconds old; something must be on offer at the cap.
The ledger
- The bot's balance is its own ledger: the budget, plus settled results, plus open trades at their worst case (everything still held counted as lost, plus any confirmed early sales). It never uses the Kalshi account total, so it can share an account with another bot.
Orders
- Save the trade to the ledger at its worst case BEFORE sending, then send one immediate-or-cancel order with Predictefy's SDK, which signs locally and sends straight to Kalshi:
client.accounts.kalshi.createOrder({ marketId: ticker, outcomeId: 'yes', side, type: 'market', amount: contracts, price, clientOrderId })
UP buys YES at the cap, snapped down to the price grid. DOWN sells YES at 1 minus the cap, snapped up, which is the same as buying NO.
- Record the fill from the response. A 4xx error (other than 408 or 429) means Kalshi rejected it, so record 0 filled. Any other error keeps the worst case until settlement reconciles it.
- Reconcile only with this order's own fills: client.accounts.kalshi.fetchFills({ ticker, limit: 200 }), matched by order_id. When the order id never came back, find it by client order id in client.accounts.kalshi.fetchOpenOrders({ ticker, status: undefined, limit: 200 }) (status undefined lists every status). An order Kalshi has no record of filled nothing.
Take-profit (skip this section if I turned it off)
- After a filled buy, check the trade every 5 seconds until 1 minute before the close, using Kalshi's free public order book.
- Our side's bid is the YES bid for UP and the NO bid for DOWN. A sale is on the table only when that bid is at least 95 cents and selling everything still held is a profit: contracts x bid - the sale fee - what those contracts cost with fees > 0.
- Then ask Jev, with its own state for this moment (plain words again):
position: "We own 3 UP contracts, bought at 56¢ each."
sell_now: "Selling all 3 now at 96¢ each locks in +$1.13 after fees."
hold_to_close: "Holding pays $1 a contract if UP wins, +$1.26 in all, and nothing if DOWN wins, -$1.74 in all."
time_left, then lead: "UP is far ahead: BTC is $62 above the target, about 1.5 typical moves for the time left." (slightly/clearly/far ahead or behind, from our side's point of view)
momentum_last_minute and momentum_last_3_minutes from our side's point of view: "moderate move against UP (down $25)", "strong move in UP's favour (up $90)", "flat (no change)".
math_model: "The math model gives UP a 97% chance of winning from here."
- Two questions:
exit: type "choice". Instructions: "We own contracts on one side of this Bitcoin market, and a buyer will pay close to the $1 they are worth if our side wins. Decide whether to sell now and lock in the profit, or hold to the close for the full $1 and risk losing it all if the lead slips." Criteria SELL: "Sell now: the lead could still slip away before the close, so locking in the profit is worth the last few cents." HOLD: "Hold to the close: the win is close to certain, so the full $1 is worth the small risk."
side_wins: type "noul", phrased for our side (for DOWN: "... will be below the target, so DOWN wins.").
- Sell when Jev's probability of SELL (answers.exit.probabilities.SELL) is at least 0.6 on 2 checks in a row. Use the probability, not the confidence score: on a two-way question a 70% lean only scores about 0.40 confidence. Any other answer, a failed call or a price below the bar resets the count.
- Closing order: UP sells YES at the bid; DOWN buys YES at 1 minus the NO bid, which Kalshi nets against the NO contracts held. Both immediate-or-cancel.
- Save the sale as unconfirmed BEFORE sending. A sale that fills nothing or is rejected is removed. A partial fill keeps watching the rest. An unknown outcome counts as unsold, ends the watch, and settlement confirms it from that order's own fills.
- In a dry run, simulate the sale against the book.
Each window
1. At the snapshot time from my strategy, settle earlier trades, then build Jev's state. Skip the window if the newest BTC price is more than 5 seconds old.
2. Print what Jev reads, ask Jev, log its answer, then apply code's rules.
3. Place the order (or simulate it in a dry run), then run take-profit until a minute before the close.
4. After the close, settle on Kalshi's result: $1 per contract still held on a win, plus what early sales brought in, minus what the fills cost and all fees.
Commands
- npm test: the unit tests.
- npm run balance: read-only; shows the total and the Crypto shard.
- npm run check: what Jev reads right now, Jev's answer and what the bot would do. It never places an order.
- npm run bot: the dry run, with fills simulated against the live order book.
- node src/main.ts --live: real money; asks me to type LIVE first.
- npm run report: scores Jev's odds against the math model and Kalshi's prices on the same windows (Brier score: the average of (odds minus the result, 1 or 0) squared; lower is better, and always saying 50% scores 0.25), how often UP actually won within each range of Jev's odds, how often the side Jev called won, the trades, and whether selling early beat holding to the result. It fills in missing results from Kalshi's public API.
- --windows=N stops after N windows.
- --test-order (or --test-order=up / --test-order=down): the next window places one small order at about the maximum stake, 2 cents above the current ask, without asking Jev, so I can see a real fill. Every limit still applies.
- Stop with Ctrl+C or a file named STOP in the folder. Keep state per mode in data/state-dry.json and data/state-live.json, and log every snapshot, everything Jev read and answered, every decision, order, early sale and result to data/events-YYYY-MM-DD.jsonl.
STEP 2: GET ME TO A SAFE FIRST RUN
When the tests pass:
1. Walk me through creating the Kalshi API key (Read all data and Trade only), saving the private key file outside the project, getting a Predictefy API key and a TypeSafe API key with some credit, and filling in the .env file.
2. Remind me to move my Kalshi balance to the Crypto shard.
3. Run npm run balance and npm run check with me, and fix anything that fails. The check must show a real Jev answer.
4. Run the dry run (npm run bot) with me for at least two windows, then npm run report.
5. Then give me the live command: node src/main.ts --live. I run it myself.
|