From dabb88a52257c91b3d118a99baeaad4097cfe124 Mon Sep 17 00:00:00 2001
From: patridunk <78499649+patridunk@users.noreply.github.com>
Date: Sun, 28 Dec 2025 22:43:57 +0100
Subject: [PATCH] docs: add API rate limits reference

Adds a document summarising typical API rate limits for demo and production environments, with guidance on handling 429 errors
---
 docs/API_RATE_LIMITS.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
 create mode 100644 docs/API_RATE_LIMITS.md

diff --git a/docs/API_RATE_LIMITS.md b/docs/API_RATE_LIMITS.md
new file mode 100644
index 00000000..f7349519
--- /dev/null
+++ b/docs/API_RATE_LIMITS.md
@@ -0,0 +1,17 @@
+# API rate limits
+
+Kalshi enforces rate limits on its API to ensure fair usage.
+
+## Demo environment
+
+- Request limit: 60 requests per minute
+- Burst: 20 requests per second
+- Consequence: Exceeding the limit returns HTTP 429
+
+## Production environment
+
+- Request limit: 180 requests per minute
+- Burst: 60 requests per second
+- Rate limits may vary by account tier
+
+If you encounter 429 responses, implement exponential backoff and respect the `Retry-After` header.