{"id":49211719,"url":"https://github.com/TKtokyo/polymarket-scan-api","last_synced_at":"2026-05-26T19:01:00.559Z","repository":{"id":346123333,"uuid":"1188572416","full_name":"TKtokyo/polymarket-scan-api","owner":"TKtokyo","description":"Automated Polymarket market scanner detecting liquidity anomalies and trade opportunities. Scans all active markets every 60s via Cron. Pay $0.018 USDC per request on Base. No API key required.","archived":false,"fork":false,"pushed_at":"2026-05-15T12:26:14.000Z","size":66,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-15T14:10:30.320Z","etag":null,"topics":["cloudflare-workers","hono","liquidity","polymarket","prediction-markets","x402"],"latest_commit_sha":null,"homepage":"https://polymarket-scan-api.tatsu77.workers.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TKtokyo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-22T09:20:18.000Z","updated_at":"2026-05-15T12:26:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/TKtokyo/polymarket-scan-api","commit_stats":null,"previous_names":["tktokyo/polymarket-scan-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TKtokyo/polymarket-scan-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TKtokyo%2Fpolymarket-scan-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TKtokyo%2Fpolymarket-scan-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TKtokyo%2Fpolymarket-scan-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TKtokyo%2Fpolymarket-scan-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TKtokyo","download_url":"https://codeload.github.com/TKtokyo/polymarket-scan-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TKtokyo%2Fpolymarket-scan-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33534563,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"ssl_error","status_checked_at":"2026-05-26T15:22:15.568Z","response_time":63,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloudflare-workers","hono","liquidity","polymarket","prediction-markets","x402"],"created_at":"2026-04-23T22:00:21.512Z","updated_at":"2026-05-26T19:01:00.547Z","avatar_url":"https://github.com/TKtokyo.png","language":"TypeScript","funding_links":[],"categories":["🌟 Ecosystem Projects"],"sub_categories":["Tools \u0026 Services"],"readme":"# Polymarket Scan API\n\nReal-time liquidity anomaly scanner for **all active Polymarket prediction markets**.\n\nEvery 60 seconds, the scanner inspects every order book on Polymarket, detects thin books / depth surges / mean-reversion setups, and returns **actionable trade recommendations** that AI agents can consume as direct if-conditions in their trading logic.\n\n**x402 paywall** \u0026mdash; micropayments on Base mainnet (USDC).\n\n---\n\n## Architecture\n\n```\nCloudflare Cron (every 60 s)\n  │\n  ├─ 1. Fetch all active markets        ← Gamma API (paginated)\n  ├─ 2. Fetch order books in 10-chunks   ← CLOB API\n  ├─ 3. Diff against previous depths     ← KV read (prev_depths)\n  ├─ 4. Score \u0026 classify anomalies\n  ├─ 5. Single KV PUT                   → SCAN_KV\n  └─ 6. R2 PUT (lightweight snapshot)   → SCAN_R2\n                                           │  │\nHTTP GET /scan/liquidity-anomaly ──────────┘  │\n  (x402 $0.018 → KV read → filter → respond) │\n                                              │\nHTTP GET /scan/history ───────────────────────┘\n  (x402 $0.005 → R2 list+get → filter → respond)\n```\n\nThe Cron trigger runs the full pipeline and writes the result to **Cloudflare KV** as a single JSON blob. The HTTP endpoint is a pure **KV read** \u0026mdash; no computation at request time, no cold starts, sub-millisecond latency.\n\n**Stack:** Cloudflare Workers + Cron Triggers + KV + R2 + Service Bindings\n\n---\n\n## Endpoints\n\n| Endpoint                      | Price            | Description                        |\n|-------------------------------|------------------|------------------------------------|\n| `GET /scan/liquidity-anomaly` | $0.018 USDC/req  | Latest scan snapshot (real-time)   |\n| `GET /scan/history`           | $0.005 USDC/req  | Time-series history (up to 24h)    |\n\n---\n\n### `GET /scan/liquidity-anomaly`\n\nRequires an `X-Payment` header with a valid x402 payment proof ($0.018 USDC on Base).\n\n#### Query Parameters\n\n| Parameter   | Type    | Default | Description                                                    |\n|-------------|---------|---------|----------------------------------------------------------------|\n| `min_score` | float   | `0.7`   | Minimum opportunity score (0\u0026ndash;1). Use `0.8` for high-confidence signals. |\n| `limit`     | integer | `10`    | Number of opportunities to return (1\u0026ndash;20).                |\n| `direction` | string  | `both`  | Filter by anomaly type: `thin`, `surge`, or `both`.            |\n\n#### Response Example\n\n```json\n{\n  \"scanned_at\": \"2025-06-15T12:00:05.123Z\",\n  \"last_update_id\": \"1718452805123\",\n  \"total_markets_scanned\": 342,\n  \"cache_age_seconds\": 18,\n  \"opportunities\": [\n    {\n      \"conditionId\": \"0xabc123...\",\n      \"title\": \"Will Bitcoin reach $100k by July 2025?\",\n      \"opportunity_type\": \"thin_book\",\n      \"opportunity_score\": 0.92,\n      \"trade_recommendation\": {\n        \"action\": \"AVOID_ENTRY\",\n        \"confidence\": 0.92,\n        \"reason\": \"spread_too_wide\",\n        \"expected_condition\": \"spread_widen\",\n        \"time_to_decay_seconds\": 45,\n        \"urgency_level\": \"medium\"\n      },\n      \"current_spread\": 0.0823,\n      \"depth_delta_60s\": -1250.50,\n      \"liquidity_usd\": 3200.00,\n      \"is_scaling_up\": false,\n      \"polymarket_url\": \"https://polymarket.com/event/bitcoin-100k-july\"\n    }\n  ]\n}\n```\n\n---\n\n### `GET /scan/history`\n\nRequires an `X-Payment` header with a valid x402 payment proof ($0.005 USDC on Base).\n\nReturns time-series scan snapshots stored in R2. Each Cron cycle (every 60 s) writes a lightweight snapshot, enabling trend analysis and historical anomaly tracking.\n\n#### Query Parameters\n\n| Parameter   | Type    | Default | Description                                                    |\n|-------------|---------|---------|----------------------------------------------------------------|\n| `hours`     | integer | `1`     | How many hours of history to retrieve (1\u0026ndash;24).            |\n| `limit`     | integer | `10`    | Maximum number of scan snapshots to return (1\u0026ndash;60).       |\n| `min_score` | float   | `0`     | Minimum opportunity score filter (0\u0026ndash;1).                  |\n\n#### Response Example\n\n```json\n{\n  \"period_hours\": 1,\n  \"data_points\": 3,\n  \"scans\": [\n    {\n      \"scanned_at\": \"2025-06-15T12:00:05.123Z\",\n      \"total_markets_scanned\": 342,\n      \"opportunity_count\": 5,\n      \"top_opportunities\": [\n        {\n          \"conditionId\": \"0xabc123...\",\n          \"title\": \"Will Bitcoin reach $100k by July 2025?\",\n          \"opportunity_type\": \"thin_book\",\n          \"opportunity_score\": 0.92,\n          \"trade_recommendation\": {\n            \"action\": \"AVOID_ENTRY\",\n            \"confidence\": 0.92,\n            \"reason\": \"spread_too_wide\",\n            \"expected_condition\": \"spread_widen\",\n            \"time_to_decay_seconds\": 45,\n            \"urgency_level\": \"medium\"\n          },\n          \"current_spread\": 0.0823,\n          \"depth_delta_60s\": -1250.50,\n          \"liquidity_usd\": 3200.00,\n          \"is_scaling_up\": false,\n          \"polymarket_url\": \"https://polymarket.com/event/bitcoin-100k-july\"\n        }\n      ]\n    },\n    {\n      \"scanned_at\": \"2025-06-15T11:59:04.456Z\",\n      \"total_markets_scanned\": 342,\n      \"opportunity_count\": 3,\n      \"top_opportunities\": []\n    }\n  ]\n}\n```\n\n#### Use Cases\n\n- **Trend detection**: Track how a market's liquidity evolves over the past hour before entering a position.\n- **Backtesting signals**: Compare anomaly scores across multiple scan cycles to validate signal persistence.\n- **Alert correlation**: Cross-reference anomaly timestamps with external events (news, whale trades).\n\n---\n\n## trade_recommendation\n\nEach opportunity includes a `trade_recommendation` object designed to be consumed directly as control flow in agent trading logic.\n\n### `action`\n\n| Value            | Meaning                                    | Agent behavior                     |\n|------------------|--------------------------------------------|------------------------------------|\n| `AVOID_ENTRY`    | Order book is thin, spread is wide         | Do not enter a position            |\n| `MONITOR`        | Liquidity is flowing in (surge detected)   | Watch for stabilization            |\n| `CONSIDER_ENTRY` | Mean reversion setup detected              | Entry may be favorable             |\n\n### Other fields\n\n| Field                    | Description                                                              |\n|--------------------------|--------------------------------------------------------------------------|\n| `confidence`             | 0\u0026ndash;1, same value as `opportunity_score`                             |\n| `reason`                 | Why: `spread_too_wide` / `liquidity_inflow` / `mean_reversion_setup`     |\n| `expected_condition`     | What comes next: `spread_widen` / `liquidity_inflow` / `mean_reversion`  |\n| `time_to_decay_seconds`  | Estimated seconds before the anomaly dissipates                          |\n| `urgency_level`          | `high` (\u0026lt; 30 s), `medium` (\u0026lt; 90 s), `low` (\u0026ge; 90 s)            |\n\n---\n\n## Scoring Logic\n\n```\nopportunity_score = min(1.0, (|depth_delta_60s| / prev_depth) * 2)\n```\n\n- `depth_delta_60s` = current total order book depth \u0026minus; previous depth (from KV)\n- `prev_depth` = total depth recorded on the previous Cron cycle (60 s ago)\n- Score is clamped to `[0, 1]`\n- A 50% depth change in 60 seconds yields a score of `1.0`\n\n| Score       | Signal strength       | Suggested action              |\n|-------------|-----------------------|-------------------------------|\n| \u0026gt; 0.9    | Extreme anomaly       | Immediate attention required  |\n| 0.8 \u0026ndash; 0.9 | Strong signal    | Act within `time_to_decay`    |\n| 0.7 \u0026ndash; 0.8 | Moderate signal  | Monitor, recheck in 60 s      |\n| \u0026lt; 0.7    | Noise (filtered out)  | Ignore                        |\n\n---\n\n## Quick Start\n\n```typescript\nimport { x402 } from \"x402-next\";\n\nconst client = x402({\n  network: \"base\",\n  // wallet or payment provider config\n});\n\nconst res = await client.get(\n  \"https://polymarket-scan-api.tatsu77.workers.dev/scan/liquidity-anomaly\",\n  { params: { min_score: 0.8, limit: 5, direction: \"both\" } }\n);\n\nfor (const opp of res.data.opportunities) {\n  const { action } = opp.trade_recommendation;\n\n  if (action === \"AVOID_ENTRY\") {\n    console.log(`SKIP ${opp.title} — spread too wide`);\n  } else if (action === \"CONSIDER_ENTRY\") {\n    console.log(`ENTRY CANDIDATE ${opp.title} — score ${opp.opportunity_score}`);\n    // Step 2: deep dive with polymarket-liquidity-api\n  }\n}\n```\n\n---\n\n## 2-Step Workflow with polymarket-liquidity-api\n\n1. **Step 1 \u0026mdash; Scan** (this API): `GET /scan/liquidity-anomaly?min_score=0.7`\n   \u0026rarr; Get a list of markets with liquidity anomalies and trade recommendations.\n2. **Step 2 \u0026mdash; Deep dive** (`polymarket-liquidity-api`): For any interesting `conditionId`, call the companion API to get the full order book snapshot, detailed spread analysis, and depth-at-price data.\n\n---\n\n## Discovery Endpoints\n\n| Path                    | Description                          |\n|-------------------------|--------------------------------------|\n| `GET /`                 | Service metadata (JSON)              |\n| `GET /.well-known/x402` | x402 payment metadata                |\n| `GET /openapi.json`     | [OpenAPI 3.0 spec](https://polymarket-scan-api.tatsu77.workers.dev/openapi.json) |\n| `GET /llms.txt`         | LLM-optimized API documentation      |\n| `POST /mcp`             | MCP Streamable HTTP (discovery-only) |\n\n---\n\n## Environment Variables\n\n| Variable          | Where              | Description                                     |\n|-------------------|--------------------|-------------------------------------------------|\n| `PAY_TO_ADDRESS`  | `wrangler.toml` or `.dev.vars` | USDC receive address for x402 payments |\n| `SCAN_KV`         | KV namespace binding | Cloudflare KV for scan result storage          |\n| `SCAN_R2`         | R2 bucket binding    | Cloudflare R2 for time-series scan history     |\n| `LIQUIDITY_API`   | Service binding      | Reference to `polymarket-liquidity-api` worker |\n\n---\n\n## Development\n\n```bash\nnpm install\nnpm run dev        # wrangler dev (local)\nnpm run deploy     # wrangler deploy (production)\nnpm run typecheck  # tsc --noEmit\n```\n\n---\n\n## License\n\nISC\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTKtokyo%2Fpolymarket-scan-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTKtokyo%2Fpolymarket-scan-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTKtokyo%2Fpolymarket-scan-api/lists"}