ADR 015: Kalshi Demo Environment Support

Status

Accepted

Context

Testing the Kalshi integration requires valid API credentials and involves real money in production. Kalshi provides a demo environment (demo-api.kalshi.co) with mock funds that mirrors production functionality. We need to support seamless switching between production and demo environments for development and testing.

Key requirements: - Safe testing without production credentials or capital risk - Same codebase for both environments (no code duplication) - Clear separation of credentials between environments - Production as the safe default

Decision

Implement a KalshiEnvironment enum with Production and Demo variants, exposed via a --kalshi-demo CLI flag.

Implementation Details

1. KalshiEnvironment Enum (src/market/kalshi_env.rs)

#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum KalshiEnvironment {
    #[default]
    Production,
    Demo,
}

impl KalshiEnvironment {
    pub fn api_base_url(&self) -> &'static str { ... }
    pub fn websocket_url(&self) -> &'static str { ... }
    pub fn api_url(&self, path: &str) -> String { ... }
    pub fn status_url(&self) -> String { ... }
}

2. URL Configuration

Environment	REST API	WebSocket
Production	https://trading-api.kalshi.com	wss://trading-api.kalshi.com/trade-api/v2/ws
Demo	https://demo-api.kalshi.co	wss://demo-api.kalshi.co/trade-api/v2/ws

3. Credential Namespacing

Environment	Key ID Variable	Private Key Variable
Production	KALSHI_KEY_ID	KALSHI_PRIVATE_KEY
Demo	KALSHI_DEMO_KEY_ID	KALSHI_DEMO_PRIVATE_KEY

4. CLI Integration

# Production (default)
cargo run --manifest-path arbiter-engine/Cargo.toml

# Demo environment
cargo run --manifest-path arbiter-engine/Cargo.toml -- --kalshi-demo

Alternatives Considered

Approach	Pros	Cons	Verdict
Enum with CLI flag	Type-safe, clear separation, safe default	Requires restart to switch	Chosen
Environment variable only	Runtime switching	Easy to misconfigure, no type safety	Rejected
Config file	Flexible	Overkill for binary choice	Rejected
Separate binaries	Complete isolation	Code duplication, maintenance burden	Rejected

Consequences

Positive

• Safe testing with mock funds before production deployment
• Same code paths exercised in both environments
• Clear credential separation prevents accidental cross-environment usage
• Production is the safe default (requires explicit --kalshi-demo to use demo)
• Consistent pattern for adding future exchange demo environments

Negative

• Requires restart to switch environments (acceptable for this use case)
• Two sets of credentials to manage

Neutral

• Similar pattern could be applied to Polymarket if they add a demo environment

Testing

• 4 unit tests for KalshiEnvironment URL generation
• Integration verified with --kalshi-demo --paper-trade
• Council review: PASS (confidence 0.85, weighted score 8.52/10)

References

• Kalshi Demo Environment Documentation
• GitHub Issue #39
• CLI Reference
• Environment Variables

Linked Requirements

• NFR-TEST-001: Kalshi demo environment support
• NFR-TEST-002: Separate credential namespacing for demo environments
• NFR-TEST-003: Environment-aware URL configuration
• NFR-TEST-004: Safe default to production environment