Grok Trading Bot: Build a Kalshi Paper Bot with Grok (Spending Limits Included)

You're my coding partner. We're building a small Kalshi bot that runs ONLY
on the Kalshi demo exchange. Paper mode is the default. Do not invent
endpoints. If a field below disagrees with the docs you fetch, stop and
quote the doc.

Read these pages first and quote the line you rely on for each endpoint:
- https://docs.kalshi.com/getting_started/demo_env
- https://docs.kalshi.com/getting_started/quick_start_authenticated_requests
- https://docs.kalshi.com/api-reference/orders/create-order-v2
- https://docs.kalshi.com/api-reference/orders/cancel-all-orders
- https://docs.kalshi.com/api-reference/order-groups/create-order-group
- https://docs.kalshi.com/api-reference/market/get-market
- https://docs.kalshi.com/getting_started/orderbook_responses

SAFETY RULES (BotCookery Safety Pack; also save them as AGENTS.md):
Secrets
- Never read, print, log or summarize .env, *.pem, *.key or any file with
  keys. Credentials come only from env vars: KALSHI_API_KEY_ID,
  KALSHI_PRIVATE_KEY_PATH (PEM file outside the repo) and XAI_API_KEY.
- Never start a web server, file server or tunnel in this folder. Never
  push or make the repo public without my OK.
Money
- The only base URL in code: https://external-api.demo.kalshi.co/trade-api/v2
- PAPER_MODE defaults to 1. A signed order or cancel only hits the network
  with PAPER_MODE=0 AND --live AND me typing exactly "I accept the risk".
  If keys are missing, exit. Never invent a key.
- A KILL file in the project folder, or BOT_KILL=1, blocks new orders.
  python cancel_all.py still runs.
- Enforce limits.json in risk.py before every order. Reject and log any
  order that breaks a limit; never retry it in a loop. Retry reads with
  bounded exponential backoff on 429/5xx.
- Research is off by default and never changes the bid.
Venue rules
- Only documented endpoints from docs.kalshi.com. Don't trade for anyone
  else, copy other traders, or share Kalshi data.
Code hygiene
- Log every decision to a local file with no secrets. Write the limit and
  kill-switch tests before the strategy.

limits.json, exactly:
  max_contracts_per_order 1
  max_open_exposure_usd 5
  max_daily_loss_usd 2
  max_orders_per_minute 3
  order_group_contracts_limit 3

risk.py, tests first. check_order(proposal, state, limits, now, kill_path)
returns allowed plus reasons. It does not raise for a bad order.
- proposal: ticker, side "bid" or "ask", count (Decimal contracts), price
  (Decimal dollars).
- state: open_exposure_usd, daily_loss_usd (non-negative dollars already
  lost today, not signed PnL), recent_order_times, group_submissions as
  (timestamp, contracts) pairs.
- Block if the KILL file exists or BOT_KILL=1.
- Block if count > max_contracts_per_order, or count <= 0, or price is not
  strictly between 0 and 1.
- A bid's cost is count * price. Block if open exposure plus that cost
  exceeds max_open_exposure_usd. Equal to the cap is allowed.
- Block if daily_loss_usd >= max_daily_loss_usd.
- Block if there are already max_orders_per_minute submissions in the
  last 60 seconds.
- The order-group limit mirrors Kalshi's rolling 15-second matched-contract
  cap. Locally, block if contracts submitted in the last 15 seconds plus
  this count would exceed order_group_contracts_limit. Say in a comment
  that the server counts fills and we count submissions.

config.toml:
  ticker = "<one demo ticker>"
  bid_price = "0.1500"          # dollars, not cents
  research_enabled = false

How to read the market (public, no auth header):
  GET /markets/{ticker}
  GET /markets/{ticker}/orderbook
Best YES ask:
  1. Use market.yes_ask_dollars when it is present and greater than 0.
  2. Otherwise use $1.00 minus the highest NO bid in
     orderbook_fp.no_dollars. Never compute "100 - X" on dollar strings.
  3. If neither exists, there is no ask. Do not bid.
title is deprecated; if it's empty, fall back to yes_sub_title.
When browsing for a ticker, pass status=open and mve_filter=exclude.

client.py:
  Sign timestamp_ms + METHOD + full path from the API root, query stripped.
  Example message: 1703123456789GET/trade-api/v2/portfolio/balance
  RSA-PSS SHA-256 (salt length = digest length) or Ed25519, then base64.
  Headers: KALSHI-ACCESS-KEY, KALSHI-ACCESS-TIMESTAMP, KALSHI-ACCESS-SIGNATURE.
  Public GETs stay unsigned so missing keys still allow a market read.
  Paper mode (default) handles POST /portfolio/order_groups/create,
  POST /portfolio/events/orders and DELETE /portfolio/events/orders on disk
  and does not open a socket for those. Persist paper orders so cancel_all.py
  in a second process can see them.

research.py, off unless research_enabled is true:
  POST https://api.x.ai/v1/chat/completions
  Authorization: Bearer $XAI_API_KEY
  Model from XAI_MODEL, default grok-4.7. stream false, temperature 0.
  The user message may contain only title, rules_primary and these prices:
  yes_bid_dollars, yes_ask_dollars, no_bid_dollars, no_ask_dollars,
  last_price_dollars. No credentials, balances, positions, previous-day
  prices or notional value. Ask for JSON:
  {"summary": "<exactly three sentences>", "probability": 0.0, "reasoning": ""}
  Log the public view and the parsed reply to logs/research.jsonl.
  If XAI_API_KEY is missing, do not call the network. A --stub flag may use
  a deterministic local stand-in and must say it is not a forecast.
  A research failure is logged and ignored. It must not block or place orders.

bot.py, one decision per run, no loop:
  1. If the kill switch is on, log and exit. Do not create an order group.
  2. Fetch the market and the order book. If the fetch fails, log and exit.
  3. If status is not "active", or there is no YES ask, or the ask is above
     bid_price, log and exit. Ask == bid_price is a yes.
  4. check_order for a bid of exactly 1 contract at bid_price.
  5. Only if that passes: POST /portfolio/order_groups/create with
     {"contracts_limit": 3} (integer). Then POST /portfolio/events/orders with
     ticker, side "bid", count "1.00", price as a 4-decimal dollar string,
     time_in_force "immediate_or_cancel", self_trade_prevention_type
     "taker_at_cross", client_order_id (UUID), order_group_id.
     Do not send GTT. It is not a valid time_in_force.
  6. Append every step to logs/decisions.jsonl. No secrets in the log.
  Track exposure and the rate limit in a local ledger.json. If you later
  read GET /portfolio/balance for the ledger, use balance_dollars or treat
  the integer balance as cents. Never divide a dollar order price by 100.

cancel_all.py: DELETE /portfolio/events/orders (paper: clear the saved paper
orders), then drop local reserved exposure. The kill switch does not apply.

Also add .gitignore (.env, *.pem, *.key, KILL, logs/), .env.example with
empty values, AGENTS.md containing the safety rules above, and a gitleaks
pre-commit hook. Explain each file in a short README. Flag anything this
prompt still doesn't specify instead of guessing.