Polymarket US Read-only
PASS WITH FIXES Tested on Composer 2.5, , result: PASS WITH FIXES. We built this toolkit from the prompt and ran it against live public Polymarket US data (3 tests passing). The optional signed balance and positions calls were not run: no real keys, orders or money. The prompt below includes the fixes from that run.
Short answer: The Polymarket US API has two hosts: public market data at https://gateway.polymarket.us (no API key needed, e.g. GET /v1/markets and GET /v1/markets/{slug}/book) and authenticated trading at https://api.polymarket.us. This recipe gives you a prompt that has your AI coding tool build a read-only Python toolkit for markets, best bid/ask and order books, plus optional balance and position reads. It places no orders.
https://gateway.polymarket.us (no key) and authenticated trading at https://api.polymarket.us.GET /v1/markets, GET /v1/market/slug/{slug}, GET /v1/markets/{slug}/book, GET /v1/markets/{slug}/bbo, GET /v1/events, GET /v1/search.pip install polymarket-us (Python 3.10+) or npm install polymarket-us (Node 18+).X-PM-Access-Key, X-PM-Timestamp, X-PM-Signature headers.https://gamma-api.polymarket.com) is public too, but the international exchange is close-only for US users. Read-only there.A small, tidy Python toolkit that lists Polymarket US markets, prints best bid/ask and the order book for any market slug, and (optionally) reads your own balance and positions with your API key. No orders.
Anyone who searched "polymarket api" and wants working code in minutes, and anyone planning a bot who needs a clean data layer first.
Not for: Placing orders. That's the next recipe, in paper mode.
Works in Claude Code, Cursor, Codex/ChatGPT, Grok or any agent that can write files. Paste it into an empty folder. Read what it builds before you run anything.
You are building a READ-ONLY Python toolkit for the Polymarket US API.
Use only endpoints documented at https://docs.polymarket.us. If you are not
sure an endpoint or field exists, stop and tell me instead of guessing.
Project: polymarket-starter/
- Python 3.10+, `requests` (or the official `polymarket-us` SDK), `python-dotenv`.
- pm.py with functions:
- list_markets(limit=20) -> GET https://gateway.polymarket.us/v1/markets
?active=true&closed=false&limit=N
(without closed=false the list can
start with markets that already closed)
- get_market(slug) -> GET /v1/market/slug/{slug}
- get_bbo(slug) -> GET /v1/markets/{slug}/bbo
- get_book(slug) -> GET /v1/markets/{slug}/book
- search(query) -> GET /v1/search?query=...
The response is {"events": [...]},
and each event holds its markets.
Print event title plus each market slug.
- cli.py: `python cli.py markets`, `python cli.py bbo <slug>`,
`python cli.py book <slug>`, `python cli.py search "<text>"`.
Pretty-print with prices as decimals (0.00-1.00) and implied % next to them.
Always print marketData.state. bestBid/bestAsk can be null (for example on
an expired market): print "no bid"/"no ask" instead of crashing.
- OPTIONAL auth.py (only if POLYMARKET_KEY_ID and POLYMARKET_SECRET_KEY are
set in the environment): read-only calls to
GET https://api.polymarket.us/v1/account/balances and
GET https://api.polymarket.us/v1/portfolio/positions, signed exactly as the
Authentication page describes (Ed25519; headers X-PM-Access-Key,
X-PM-Timestamp in ms, X-PM-Signature over timestamp+METHOD+path).
- Never implement order placement in this project.
- Handle 429 with exponential backoff (1s, 2s, 4s, then give up). Stay well
under 25 requests/second. Cache market metadata for 5 minutes.
- Secrets: read keys only from environment variables. Create .env.example
with empty placeholders, add .env to .gitignore, never print keys.
- Write a README with setup steps and 3 example commands.
- Add pytest tests that mock HTTP responses (no live calls in tests).
Before writing code, show me the file plan. After writing it, tell me exactly
which commands to run.polymarket-starter) and open it in your AI coding tool. Drop the Safety Pack rules file and .gitignore in first.pm.py and make sure every URL starts with https://gateway.polymarket.us/v1/ or https://api.polymarket.us/v1/.python -m venv .venv && source .venv/bin/activate
pip install requests python-dotenv pytest
python cli.py markets
python cli.py search "temperature"
events[]), each with its markets.python cli.py bbo <slug> and python cli.py book <slug>. The bbo response nests prices under marketData (for example bestBid.value, bestAsk.value, currentPx.value). If state is MARKET_STATE_EXPIRED or the bid and ask are null, the market is finished; pick another.price.value always refers to the long (YES) side. To trade the NO side at price X you set price.value = 1.00 - X. Your toolkit should label this clearly so a future bot doesn't get it backwards..env, never in code, then run python cli.py balance.pytest. They should pass without internet.https://gamma-api.polymarket.com/markets?closed=false&limit=5 is public. Only use it for research. US users can't open positions on the international exchange, so don't build trading on it.This recipe never places orders, so it's "paper" by design. Two habits to build now, because the next recipes depend on them:
logs/market_data.jsonl. When you build the bot, the paper ledger replays against this.POLYMARKET_KEY_ID, fix that, because it means keys are leaking into code paths that don't need them.When you're ready to simulate orders, go to Build a Polymarket Bot with Claude Code (Paper Mode).
Tick every box before the bot touches real money. The full rules file, .gitignore and pre-commit hook are in the Safety Pack.
.env and *.pem are in .gitignore, and your AI tool is blocked from reading them (see the Safety Pack).touch KILL) stops new orders immediately, and a second command cancels every resting order through the venue's cancel-all endpoint.--live flag and a typed confirmation, and you only flip it after days of clean paper logs./v1/orders and /v1/order/; there should be zero hits..env only. If it ever lands in a chat, a screenshot or git, revoke it at polymarket.us/developer.Endpoints and rules were checked against these pages on Oct 19, 2026. APIs change, so if something here disagrees with the official docs, trust the docs and tell us.
Not for market data. Polymarket US public endpoints at https://gateway.polymarket.us (markets, events, order books, best bid/offer, search) need no key. You only need a key for trading, positions and balances on https://api.polymarket.us.
Polymarket US is a separate, CFTC-regulated, USD-based exchange for US residents with its own API (docs.polymarket.us). International Polymarket is crypto-based, with its own Gamma, CLOB and Data APIs (docs.polymarket.com), and it's close-only for the United States.
Create an account in the Polymarket US app, complete identity verification, then sign in at polymarket.us/developer with the same login method and create a key. You get a Key ID and a Secret Key, and the secret is shown only once.
The retail API allows 25 requests per second, shared across most endpoints and enforced per source IP. A few RFQ endpoints are limited to 1 request per second. A 429 means wait at least a second and back off.
Yes. pip install polymarket-us (Python 3.10+), and there's a TypeScript SDK at npm install polymarket-us (Node 18+). Both handle request signing.
One new build recipe, one safety tip, and API changes worth knowing about. Free. No picks, ever.
Step-by-step: use Claude Code to build a Polymarket US trading bot that runs in paper mode by default, with a local paper ledger, order preview, hard position limits and a kill switch.
An honest guide to building a trading bot with Claude, Claude Code or Claude AI: where it helps, where it fails, and a safe Kalshi-demo starter prompt with a rules file, deny settings, limits and a kill switch.
Build a personal alert monitor that compares prices for the same event on Kalshi and Polymarket US and flags gaps after fees. Alerts only, no auto-trading, with an honest look at why most "arbitrage bots" don't work.