diff --git a/MARKETS_NOTES.md b/MARKETS_NOTES.md
new file mode 100644
index 0000000..c738796
--- /dev/null
+++ b/MARKETS_NOTES.md
@@ -0,0 +1,40 @@
+# Markets Notes
+
+This file complements the main README by outlining a few practical
+considerations when working with Kalshi markets from the starter code.
+
+## Environment
+
+Make sure your environment variables are set correctly:
+
+- `KALSHI_API_KEY`
+- `KALSHI_API_SECRET`
+- `KALSHI_ENV` (`demo` or `prod`)
+
+Use `check_env.py` to verify that everything is configured before
+calling any market-related endpoints.
+
+## Pagination and filtering
+
+The Kalshi API may return paginated results. When you replace the
+placeholder logic in `scripts/print_markets.py` with real API calls:
+
+- check whether the client or endpoint supports pagination parameters,
+- avoid loading a very large number of markets in a single request.
+
+## Error handling
+
+When fetching markets:
+
+- handle network errors (timeouts, connection resets),
+- handle authentication failures (invalid or expired credentials),
+- log unexpected responses for debugging.
+
+## Demo vs production
+
+Always verify which environment you are targeting:
+
+- `KALSHI_ENV=demo` for testing,
+- `KALSHI_ENV=prod` for live trading.
+
+Never reuse demo credentials in production or vice versa.
diff --git a/env.sample b/env.sample
new file mode 100644
index 0000000..bfe0669
--- /dev/null
+++ b/env.sample
@@ -0,0 +1,8 @@
+# Example environment variables for kalshi-starter-code-python
+
+# API credentials for Kalshi
+KALSHI_API_KEY=your_api_key_here
+KALSHI_API_SECRET=your_api_secret_here
+
+# Environment: "demo" or "prod"
+KALSHI_ENV=demo