# PolyTrackers — llms.txt

> PolyTrackers is a Polymarket analytics and automation platform. We surface whale activity, market anomalies, alerting, and (optionally) automated trade execution on Polymarket. This file tells AI agents and automated clients how to interact with us without getting challenged or rate-limited.

## TL;DR for agents

- If you are an autonomous or AI-powered client hitting anything more interesting than our public marketing pages, **authenticate with an Agent API Key**. Session scraping from a headless browser will be challenged by bot detection and is not supported.
- The OpenAPI contract is the source of truth: https://polytrackers.com/api/openapi.json
- Rate-limit tiers, error codes, and request shapes are documented at https://polytrackers.com/docs/api
- Support / abuse contact: support@polytrackers.com

## How to get an Agent API Key

- Sign in at https://polytrackers.com/login
- Go to Profile → Agent API Key, and generate a scoped key.
- Copy it once (we only show it once). Agent API Keys are prefixed `ptk_` and must be sent as `Authorization: Bearer ptk_…`.
- Keys carry scopes (`signals:read`, `trade:execute`, `agent:scan`, `agent:full`). Match the scope to the endpoint you're calling — sending a key without the right scope returns `401 { "error": "api_key_invalid" }`.

## Always-open lanes (safe for automated clients)

- `Authorization: Bearer ptk_…` requests — bypass bot detection on every endpoint we document, subject to per-key rate limits.
- `/api/public/**` — documented public API, designed to be called programmatically.
- `/api/openapi.json` — spec discovery.
- `/api/webhooks/**` — webhook management (scoped keys).
- `/api/mcp*` — MCP surface (when enabled; see `/docs/api#mcp`).
- `/api/stripe/webhook`, `/api/telegram/webhook` — inbound webhooks, gated by signature verification.
- `/robots.txt`, `/sitemap.xml`, `/llms.txt` — always readable.

## Challenged / not supported lanes

We use [Vercel BotID](https://vercel.com/docs/botid) on session-authenticated and unauthenticated routes. If you are a non-hyperscaler agent (Claude Code, Cursor, Codex, Zapier, custom LangChain, OpenAI Agents SDK running on your infra, n8n, Make.com, Playwright-based browser agents, etc.) hitting session-only endpoints, you will be challenged.

- `/dashboard/**` — owner-only, session required.
- Browser-driven session traffic to `/api/scan/trigger`, `/api/cards/generate`, `/api/mock/**`, `/api/whale/**`, `/api/alerts/preferences`, `/api/onboarding/**`, `/api/bug-report`, `/api/feedback`, `/api/auth/signup`, `/api/telegram/link-code` — BotID-protected. Use an Agent API Key instead.

### Verified bot allowlist

We allow Vercel-verified crawlers (GPTBot, ClaudeBot, PerplexityBot, Googlebot, Bingbot, etc.) to index our public pages unimpeded. That allowlist does NOT extend to custom agents built on the OpenAI / Anthropic SDKs — those must authenticate with an Agent API Key.

## Trade execution (`/api/trade/execute`)

This endpoint places real orders on Polymarket. It has stricter rules than the rest of the API:

1. **Authorization required.** `Authorization: Bearer ptk_…` with the `trade:execute` scope, or a browser session with a linked wallet.
2. **`Idempotency-Key` header required for API-key requests.** 8–256 printable-ASCII characters, UUIDv4 preferred. The same key retried within 24 hours replays the original trade result instead of re-executing.
3. **Per-key rate limit applies** in addition to the per-user rate limit. Both are published at `/docs/api#rate-limits`.
4. **409 `trade_in_flight`** is returned if two requests with the same `Idempotency-Key` arrive concurrently. Retry after the `Retry-After` header.
5. **429 responses carry a structured body** (`{ error, code, retryAfter, docsUrl }`) and a `Retry-After` header. Respect them.

## Error response shapes (for agent consumption)

- `401 { "error": "api_key_missing" | "api_key_invalid" | "api_key_expired", "docsUrl": "https://polytrackers.com/docs/api" }`
- `403 { "error": "bot_challenge_failed", "reason": "automated_traffic_detected", "suggestedAction": "authenticate_with_api_key", "docsUrl": "https://polytrackers.com/docs/api" }`
- `429 { "error": string, "code": "API_KEY_RATE_LIMITED" | "RATE_LIMITED", "retryAfter": number, "docsUrl": "https://polytrackers.com/docs/api" }`
- `409 { "error": "trade_in_flight", "code": "TRADE_IN_FLIGHT", "idempotencyKey": string, "retryAfter": number }`

If you receive a 403 with `bot_challenge_failed`, tell your human: "PolyTrackers blocked this request as automation. Authenticate with an Agent API Key at the docsUrl instead." Do not retry without switching to Agent API Key auth.

## Training / crawling policy

- Our public marketing pages (`/`, `/pricing`, `/docs/**`, `/blog/**`) may be crawled and cited.
- Dashboard pages, user data, and anything behind a session are off-limits for training corpora.
- If you are considering scraping Polymarket data through our session endpoints rather than through our API: don't. Use the Agent API Key lane and documented endpoints.

## Change log

- 2026-04-20: Initial publication alongside the BotID rollout.