# sswadkar/kalshi-interface architecture

> Architecture diagram of the GitHub repository sswadkar/kalshi-interface, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sswadkar/kalshi-interface
- Repository: https://github.com/sswadkar/kalshi-interface

## Overview

#### Purpose and Entry Points
This repository is a lightweight Kalshi trading integration: a FastAPI service exposes status and trading operations, while shared Python logic authenticates Kalshi API calls and calculates position metrics. The operational entry point is `server.py`; core API/client and accounting logic resides in `kalshi_positions.py`. A minimal browser-facing page is available at `static/index.html`.

#### Service Runtime and Deployment
The service runs as Python/FastAPI, locally via `python server.py` or in a container defined by `Dockerfile`. Runtime configuration is environment-driven, selecting demo versus production credentials and a monitored event ticker. Dependencies are declared in `requirements.txt`.

Relevant paths: `server.py`, `Dockerfile`, `requirements.txt`.

#### Kalshi Authentication Boundary
Outbound requests to Kalshi pass through PSS/RSA signing logic in the core client layer. Private keys are environment-isolated, with distinct demo and production key locations. Key IDs and active environment are supplied externally through environment variables rather than embedded application logic.

Relevant paths: `kalshi_positions.py`, `api_keys/demo/private_key.pem`, `api_keys/prod/private_key.pem`.

#### Market and Position Polling
The server maintains real-time, in-memory state through two background polling loops: market/position refreshes run at roughly 0.5-second intervals, while resting-order refreshes run roughly every three seconds. This state is the source for the status API, creating a boundary between Kalshi’s remote API responses and locally served read status.

Relevant paths: `server.py`, `kalshi_positions.py`.

#### Trading API Flow
FastAPI endpoints accept buy, sell, and cancellation requests, delegate execution to the signed Kalshi client, and return the resulting order payload. Trading is an externally side-effecting boundary; orders are submitted to Kalshi rather than persisted in a local database.

Relevant paths: `server.py`, `kalshi_positions.py`.

#### Position Accounting
The core logic derives per-market liquidation value, realized PnL, and net exposure from fetched positions and market prices. It also applies the repository’s taker-fee model, `0.07 × P × (1 − P)`, when interpreting order costs and fees.

Relevant paths: `kalshi_positions.py`.

#### External Interfaces
Primary external dependency: Kalshi’s trading API, accessed with signed HTTP requests. Consumers can use the HTTP API on port 8000 or the included static status/UI asset. The repository has no indicated persistent datastore, queue, or streaming transport; process memory is the live state store.

Relevant paths: `server.py`, `static/index.html`, `kalshi_positions.py`.

Main entry points: [`kalshi_positions.py`](https://github.com/sswadkar/kalshi-interface/blob/main/kalshi_positions.py) (Signed Kalshi client), [`server.py`](https://github.com/sswadkar/kalshi-interface/blob/main/server.py) (Server runtime), [`static/index.html`](https://github.com/sswadkar/kalshi-interface/blob/main/static/index.html) (Status page), [`Dockerfile`](https://github.com/sswadkar/kalshi-interface/blob/main/Dockerfile) (Container runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_service["FastAPI Service"]
  node_server["Server runtime<br/>FastAPI<br/>[server.py]"]
  node_status_api["Status API<br/>read endpoints<br/>[server.py]"]
  node_trading_api["Trading API<br/>order endpoints<br/>[server.py]"]
  node_market_poller["Market/position poller<br/>background loop<br/>[server.py]"]
  node_orders_poller["Resting-order poller<br/>background loop<br/>[server.py]"]
  node_live_state[("In-memory live state<br/>process memory<br/>[server.py]")]
  node_browser_ui["Status page<br/>static browser UI<br/>[index.html]"]
  node_container["Container runtime<br/>Docker image"]
  node_dependencies["Python dependencies<br/>package manifest<br/>[requirements.txt]"]
end

subgraph group_core["Trading Core"]
  node_kalshi_client["Signed Kalshi client<br/>API client"]
  node_position_accounting["Position accounting<br/>metrics logic"]
end

subgraph group_external["External Boundaries"]
  node_environment{{"Runtime environment<br/>environment variables"}}
  node_demo_key["Demo private key<br/>RSA key<br/>[private_key.pem]"]
  node_prod_key["Production private key<br/>RSA key<br/>[private_key.pem]"]
  node_kalshi_api["Kalshi Trading API<br/>external API"]
end

node_container -->|"runs"| node_server
node_dependencies -.->|"provides runtime packages"| node_server
node_browser_ui -->|"uses HTTP API"| node_server
node_server -->|"hosts"| node_status_api
node_server -->|"hosts"| node_trading_api
node_server -->|"starts"| node_market_poller
node_server -->|"starts"| node_orders_poller
node_market_poller -->|"fetches markets and positions"| node_kalshi_client
node_orders_poller -->|"fetches resting orders"| node_kalshi_client
node_kalshi_client -->|"supplies positions and prices"| node_position_accounting
node_market_poller -->|"updates"| node_live_state
node_orders_poller -->|"updates"| node_live_state
node_position_accounting -->|"derives metrics"| node_live_state
node_status_api -->|"reads"| node_live_state
node_trading_api -->|"submits and cancels orders"| node_kalshi_client
node_kalshi_client -->|"signed HTTP requests"| node_kalshi_api
node_environment -.->|"selects environment and key ID"| node_kalshi_client
node_demo_key -.->|"demo signing key"| node_kalshi_client
node_prod_key -.->|"production signing key"| node_kalshi_client

click node_server "https://github.com/sswadkar/kalshi-interface/blob/main/server.py"
click node_status_api "https://github.com/sswadkar/kalshi-interface/blob/main/server.py"
click node_trading_api "https://github.com/sswadkar/kalshi-interface/blob/main/server.py"
click node_market_poller "https://github.com/sswadkar/kalshi-interface/blob/main/server.py"
click node_orders_poller "https://github.com/sswadkar/kalshi-interface/blob/main/server.py"
click node_live_state "https://github.com/sswadkar/kalshi-interface/blob/main/server.py"
click node_kalshi_client "https://github.com/sswadkar/kalshi-interface/blob/main/kalshi_positions.py"
click node_position_accounting "https://github.com/sswadkar/kalshi-interface/blob/main/kalshi_positions.py"
click node_demo_key "https://github.com/sswadkar/kalshi-interface/blob/main/api_keys/demo/private_key.pem"
click node_prod_key "https://github.com/sswadkar/kalshi-interface/blob/main/api_keys/prod/private_key.pem"
click node_browser_ui "https://github.com/sswadkar/kalshi-interface/blob/main/static/index.html"
click node_container "https://github.com/sswadkar/kalshi-interface/blob/main/Dockerfile"
click node_dependencies "https://github.com/sswadkar/kalshi-interface/blob/main/requirements.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_status_api,node_trading_api,node_market_poller,node_orders_poller,node_live_state,node_browser_ui,node_container,node_dependencies toneBlue
class node_kalshi_client,node_position_accounting toneAmber
class node_environment,node_demo_key,node_prod_key,node_kalshi_api toneMint
```

## Components

### FastAPI Service

- [Server runtime](https://github.com/sswadkar/kalshi-interface/blob/main/server.py): FastAPI · Operational entry point and HTTP API host. · `server.py`
- [Status API](https://github.com/sswadkar/kalshi-interface/blob/main/server.py): read endpoints · `server.py`
- [Trading API](https://github.com/sswadkar/kalshi-interface/blob/main/server.py): order endpoints · Accepts buy, sell, and cancellation requests. · `server.py`
- [Market/position poller](https://github.com/sswadkar/kalshi-interface/blob/main/server.py): background loop · Refreshes live market and position state about every 0.5 seconds. · `server.py`
- [Resting-order poller](https://github.com/sswadkar/kalshi-interface/blob/main/server.py): background loop · Refreshes resting orders about every three seconds. · `server.py`
- [In-memory live state](https://github.com/sswadkar/kalshi-interface/blob/main/server.py): process memory · Local read model for status responses. · `server.py`
- [Status page](https://github.com/sswadkar/kalshi-interface/blob/main/static/index.html): static browser UI · `static/index.html`
- [Container runtime](https://github.com/sswadkar/kalshi-interface/blob/main/Dockerfile): Docker image · `Dockerfile`
- [Python dependencies](https://github.com/sswadkar/kalshi-interface/blob/main/requirements.txt): package manifest · `requirements.txt`

### Trading Core

- [Signed Kalshi client](https://github.com/sswadkar/kalshi-interface/blob/main/kalshi_positions.py): API client · Signs outbound Kalshi HTTP requests with RSA/PSS. · `kalshi_positions.py`
- [Position accounting](https://github.com/sswadkar/kalshi-interface/blob/main/kalshi_positions.py): metrics logic · Calculates liquidation value, realized PnL, net exposure, and taker fees. · `kalshi_positions.py`

### External Boundaries

- **Runtime environment**: environment variables · Selects demo or production credentials and monitored ticker.
- [Demo private key](https://github.com/sswadkar/kalshi-interface/blob/main/api_keys/demo/private_key.pem): RSA key · `api_keys/demo/private_key.pem`
- [Production private key](https://github.com/sswadkar/kalshi-interface/blob/main/api_keys/prod/private_key.pem): RSA key · `api_keys/prod/private_key.pem`
- **Kalshi Trading API**: external API

## Connections

- Container runtime → Server runtime: runs
- Python dependencies → Server runtime: provides runtime packages
- Status page → Server runtime: uses HTTP API
- Server runtime → Status API: hosts
- Server runtime → Trading API: hosts
- Server runtime → Market/position poller: starts
- Server runtime → Resting-order poller: starts
- Market/position poller → Signed Kalshi client: fetches markets and positions
- Resting-order poller → Signed Kalshi client: fetches resting orders
- Signed Kalshi client → Position accounting: supplies positions and prices
- Market/position poller → In-memory live state: updates
- Resting-order poller → In-memory live state: updates
- Position accounting → In-memory live state: derives metrics
- Status API → In-memory live state: reads
- Trading API → Signed Kalshi client: submits and cancels orders
- Signed Kalshi client → Kalshi Trading API: signed HTTP requests
- Runtime environment → Signed Kalshi client: selects environment and key ID
- Demo private key → Signed Kalshi client: demo signing key
- Production private key → Signed Kalshi client: production signing key