Mapping Kalshi Demo Mode to Payment Staging Environment Conventions for Bot Developers

Testing a Kalshi bot requires three connected stages, namely stateful simulation, Kalshi demo, and a bounded production canary. Demo is a genuine staging layer for authentication, endpoints, and order mechanics, but it does not establish production liquidity, realistic account history, or resilient event handling. Mapping those limits to payment staging conventions makes the release decision depend on evidence.

Why bot developers need a fidelity checklist before moving from Kalshi demo to production

A bot works in demo, its developer changes the host and credentials, and production exposes a failure that the demo tests never exercised. Authentication succeeds, but the bot encounters market state, portfolio history, or event timing outside its tested assumptions. The plumbing was not the weak point. For developers responsible for automated trading, the release question is therefore not simply whether the bot can place an order, but which production behaviors its tests actually cover.

Payment staging provides a useful frame for that question. It separates proof that an integration works from proof that its surrounding conditions are realistic. A Kalshi fidelity checklist needs the same distinction, with explicit gates for the gaps that a successful demo run leaves unresolved.

What Kalshi's demo environment actually is and how it is structured

Kalshi's developer guide describes demo as a testing environment with mock funds and the same Trade API v2 endpoint structure as production. It also warns that demo market prices may not reflect real markets. Demo is a separate paper-trading sandbox. It has its own base URL, accounts, and API keys, and new accounts require mock funding before order logic can be tested.

That separation extends to credentials, which work only in their respective environments. Mixing a demo key with production endpoints, or the reverse, causes authentication failures because accounts do not share credentials. Market data endpoints are public, but trading and portfolio calls need signed requests in both environments. WebSocket connections also need API key authentication, even when the channels they subscribe to carry public data.

The authentication and signing layer that transfers cleanly to production

RSA-PSS authentication uses the same mechanism in demo and production. Kalshi's developer guide specifies concatenating the timestamp, HTTP method, and request path, then signing with the private key using RSA-PSS and SHA-256. The request headers contain the key ID, timestamp, and signature. Moving to production changes the host and key pair while retaining the signing implementation.

Key handling remains a separate operational responsibility. The account setup supports Ed25519 or RSA keys, and the private key is shown once and cannot be retrieved again. The release practice is to scope bot keys to read and trade only, with withdraw permission disabled. The private key belongs outside the codebase, in environment variables or a secrets manager, never in version control. These controls apply equally to both environments, so demo is also a place to establish the credential discipline production requires.

The endpoint and order mechanics that carry over — and where the June 2026 mutation endpoint removal matters

Order placement, amendment, and cancellation use the same endpoint structure in both environments, so demo can test the request plumbing used in production. The data hierarchy is consistent too, with Series containing Events and Events containing Markets. Tickers follow the same structured format. A client can thus test market identification and order handling without a separate model of the API just for demo.

Endpoint compatibility also depends on API currency. The legacy /portfolio/orders mutation endpoints were removed in June 2026, so a bot written against them needs more than a host change. To pass the demo gate, the bot must use CreateOrder V2, POST /portfolio/events/orders, with the current SDK version in place of the removed mutation endpoints. Beta endpoints present a separate risk because they can change without notice in either environment and should not support a production strategy. Even current, stable endpoint coverage proves only that the bot speaks the API correctly.

The market state gap — why demo order books do not replicate production liquidity

Demo market behavior need not represent real-market behavior, a documented limitation. A resting limit order, a partial fill, and a full fill can each demonstrate that the client handles the corresponding order state. None establishes that production depth or spreads will produce the same outcome. The distinction is between handling a transition and predicting when it will occur.

That distinction is central to testing a trading strategy. Slippage models, position-sizing rules, and cross-platform arbitrage signals depend on liquidity assumptions that demo cannot validate. A profitable demo session is evidence about workflow. For the same reason, paper-trading results cannot establish how a strategy would perform under real liquidity merely because the orders were accepted.

The appropriate boundary is precise. Demo can exercise the path from resting order through partial fill, full fill, position, and settlement, while leaving the market conditions that select each transition unproven. Strategies that depend on those conditions need a bounded production canary. That live stage tests assumptions left open by artificial liquidity, after the API checks have passed in demo.

The pre-seeded data gap — empty demo accounts and what that breaks for integration testing

New demo accounts do not begin with funds or positions. Portfolio readers, fill reconciliation, and settlement processing need account history so tests can cover all their logic. Without that history, a successful response may test only the bot's handling of an empty account.

Payment API staging environments typically provide test accounts, card numbers, and transaction histories to reduce this bootstrapping burden. Kalshi demo does not offer an equivalent. Developers must keep setup fixtures that fund the account, place seeding orders, and check positions before tests can do more than read an empty account. This preparation adds manual overhead and fragility to CI because the intended starting state must exist before the behavior under test can be evaluated.

Funding and execution also require separate diagnoses. A missing balance and an unfilled order are different failure states, even if both leave a test without the expected position. Keeping those distinctions visible prevents a setup failure from being mistaken for evidence about order logic or liquidity.

The webhook and event delivery gap — what demo does not fire and why that matters for bot resilience

A successful request does not prove that a bot will correctly handle the fill notification, settlement event, or later order-state change on which its next action depends. Kalshi documents WebSocket channels for tickers, order book deltas, public trades, and authenticated fills in both environments. Demo does not, however, guarantee realistic event sequencing under production load. The gap is controllable coverage.

Mature payment staging systems set a useful comparison through webhook retries on non-2xx responses, configurable delivery failures, and manual redelivery. Kalshi demo does not expose comparable webhook fault controls. Developers cannot make demo send 429s, partial responses, duplicate delivery, or delayed settlement events on demand. Consequently, ordinary demo activity cannot establish that retry logic, idempotency handling, and fallback paths have all been exercised.

Rate limiting makes that omission especially consequential for automated trading. Trading-endpoint 429 handling is a critical path, and passing normal requests does not test it. The current rate limit tier is available through GET /account/api-limits, but knowing the allowance is different from testing the response when requests are limited. Demo does not reliably reproduce that pressure at production scale. Controlled fault injection must therefore complement the real API connection.

How stateful simulation fills the gaps demo leaves open

The three gaps concern connected state over time. Market conditions shape fills, fills change positions, and later events affect the portfolio and settlement logic. A fixed response cannot represent that chain. A stateless stub may return an acceptable order-placement payload, yet fail to model the next request whose correct response depends on what the first request changed.

A stateful simulator can preserve those dependencies across sequential calls. It tracks resting orders and partial fills, updates positions, and models settlement payouts as transitions that build on one another. Pre-seeded market and portfolio data supplies the starting conditions that empty demo accounts lack. Lifecycle events and deliberate faults then exercise the bot's asynchronous handling under repeatable conditions.

Simulation still has a boundary of its own. Realistic fixtures can test the consequences of liquidity assumptions without proving that those assumptions match the live market. Continuous verification against the live API before each release is also necessary to prevent the simulator from drifting. An outdated model can produce the same false confidence as a demo run whose limits were never identified.

How do you test a Kalshi bot before going live? A three-tier pipeline

The pipeline starts with local stateful simulation. This first tier validates order transitions, position and portfolio logic, settlement handling, and event sequences against pre-seeded data. Injected 429s, partial fills, partial responses, and delayed settlement exercise retries, idempotency, and fallback behavior. No live credentials are needed at this stage. The output is repeatable CI evidence that the bot handles the modeled states and faults correctly, ready for testing against the real API surface.

The second tier moves that implementation into Kalshi demo. Here the tests validate signing, endpoint plumbing, WebSocket authentication and subscriptions, and the full authenticated request lifecycle. CreateOrder V2 must work with the current SDK. A test journal records the question tested, intended order, observed fill, remaining order, position, and result so that failures can be diagnosed without treating demo fill rates as production expectations.

The third tier takes that integration into a small-capital production canary. Its purpose is to exercise real liquidity, rate limits, and event delivery timing under bounded exposure. Public market data endpoints have more generous limits than trading endpoints and support liquidity observation before sizing a live position. The canary therefore supplies the market evidence missing from the earlier stages. Production launch remains gated on that evidence.

The fidelity checklist — what to verify at each tier before moving to the next

Before leaving the simulator tier, confirm that resting orders, partial fills, full fills, and resulting positions produce the correct downstream portfolio state. Settlement handling must set both the balance and the position to the right values. Injected 429s must exercise bounded, idempotent retries. Tests must also show that partial responses and delayed events reach the intended fallback paths in the code.

Before leaving the demo tier, confirm valid RSA-PSS authenticated responses from GET /portfolio/balance before testing any order endpoint. Confirm that order creation uses POST /portfolio/events/orders and that no order mutations depend on the legacy endpoints removed in June 2026. WebSocket authentication must succeed for the bot's subscriptions, with fill and order-state event handling exercised for the relevant channels. Check the rate limit tier through GET /account/api-limits. Its allowance must match the bot's expected request cadence.

Before leaving the production canary tier, check that live order book depth and spread match what the strategy assumes about liquidity. Compare fill rates and partial-fill handling with the behavior tested in simulation. Confirm that no beta endpoints remain in the production call path. The API key must permit read and trade only, with withdraw disabled, and its private key must remain outside the codebase in environment variables or a secrets manager.

These gates are release criteria that require ongoing verification. The June 2026 endpoint removal illustrates why both the simulator and the checklist must stay current with the live API. A previous pass cannot establish compatibility with an API surface that has since changed.