{ "openapi": "3.1.0", "info": { "title": "TickTape API", "version": "1.0.0", "summary": "Independent pre-flight for Polymarket orders and copy trading.", "description": "OK / CAUTION / VETO verdicts on Polymarket orders and COPY / WATCH / VETO ratings on wallets, always with reasons and numbers. Verdicts are deterministic arithmetic on live order books plus Polymarket's published 2026 taker-fee schedule (fee/share = rate * p * (1-p)) - not predictions and not investment advice. No custody, no execution, no account required. Humans can read. Agents can buy.\n\nAccess model: live calls are paid from the first request - HTTP 402 is the whole onboarding. Every live endpoint returns HTTP 402 with x402 payment requirements (USDC on Base) until paid. Free: append `sandbox=1` to any of the four tools for a deterministic example response (unlimited, never charged); append `x402_probe=1` to see payment requirements without paying; preflight_copy QUEUED responses are always free. Fast lane: buy credits once via POST /api/credits and authenticate with a bearer token (~0.4s responses, half price per call).\n\nOperator safety (enforce in code, not prompts): never pay more than $0.10 per TickTape call; set a daily spend cap; only pay endpoints under https://ticktape.cc/; verify payTo matches https://ticktape.cc/llms.txt; asset must be USDC on Base (eip155:8453, 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913); on retry reuse the same payment authorization.\n\nCanonical machine spec: https://ticktape.cc/llms.txt. Machine manifest: https://ticktape.cc/agent.json. Versioning: date-based via the X-API-Version response header (current 2026-07-14); breaking changes bump the date and are announced in llms.txt. Long-running wallet computations use an async-job pattern: HTTP 202 + Retry-After on /api/preflight_copy (QUEUED), poll the same call until 200.", "contact": { "name": "TickTape", "email": "hello@ticktape.cc", "url": "https://ticktape.cc" }, "termsOfService": "https://ticktape.cc/terms" }, "servers": [ { "url": "https://ticktape.cc", "description": "Production (Cloudflare Pages Functions)" } ], "tags": [ { "name": "preflight", "description": "Pre-flight verdicts on live Polymarket orders" }, { "name": "wallets", "description": "Copy-trading wallet ratings (leaderboard and red list)" }, { "name": "payment", "description": "Credits and the x402 fast lane" } ], "paths": { "/api/preflight_trade": { "get": { "operationId": "preflightTradeGet", "tags": [ "preflight" ], "summary": "Pre-flight verdict for a Polymarket order", "description": "Deterministic arithmetic on the live CLOB book plus the 2026 taker-fee schedule. Identify the market by `slug` + `outcome` (polymarket.com/event/ URLs work; for multi-outcome events pass a candidate name, partial match OK - a wrong outcome returns the candidate list) or by `token_id`. Live calls are paid from the first request: HTTP 402 (x402). Price per call: $0.02 USDC, or 1 credit with a bearer token. Free integration testing: `sandbox=1`.", "security": [ {}, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/slug" }, { "$ref": "#/components/parameters/outcome" }, { "$ref": "#/components/parameters/tokenId" }, { "$ref": "#/components/parameters/side" }, { "$ref": "#/components/parameters/usd" }, { "$ref": "#/components/parameters/maxSlippageC" }, { "$ref": "#/components/parameters/vetoSlippageC" }, { "$ref": "#/components/parameters/maxBookAgeS" }, { "$ref": "#/components/parameters/sandbox" }, { "$ref": "#/components/parameters/x402Probe" }, { "$ref": "#/components/parameters/paymentSignatureHeader" }, { "$ref": "#/components/parameters/xPaymentHeader" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional client idempotency key; paid responses are also idempotent per x402 payment authorization (same signed authorization -> cached response, never double-charged)" } ], "responses": { "200": { "$ref": "#/components/responses/PreflightTradeOk" }, "400": { "description": "Error (JSON, never HTML). 4xx errors are never charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "500": { "description": "Server error (JSON, never HTML) - never charged; retry with the same payment authorization returns the cached response if the charge went through.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "preflightTradePost", "tags": [ "preflight" ], "summary": "Pre-flight verdict for a Polymarket order (JSON body)", "description": "Same behavior as GET; parameters go in the JSON body. `sandbox` and `x402_probe` are also accepted as query parameters.", "security": [ {}, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/sandbox" }, { "$ref": "#/components/parameters/x402Probe" }, { "$ref": "#/components/parameters/paymentSignatureHeader" }, { "$ref": "#/components/parameters/xPaymentHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreflightTradeRequest" }, "example": { "slug": "bitcoin-up-or-down-july-13-3pm-et", "outcome": "Up", "side": "BUY", "usd": 250, "max_slippage_c": 1.0, "veto_slippage_c": 3.0, "max_book_age_s": 60 } } } }, "responses": { "200": { "$ref": "#/components/responses/PreflightTradeOk" }, "400": { "description": "Error (JSON, never HTML). 4xx errors are never charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "500": { "description": "Server error (JSON, never HTML) - never charged; retry with the same payment authorization returns the cached response if the charge went through.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/leaderboard": { "get": { "operationId": "leaderboardGet", "tags": [ "wallets" ], "summary": "Wallets rated COPY or WATCH for copy trading", "description": "Machine JSON of wallets worth copying, with fee-inclusive copier ROI, out-of-sample validation and reasons. Method: first-entry mirror $5/trade, 2c slippage, explicit 2026 taker fees. Live calls are paid from the first request: HTTP 402 (x402). Price per call: $0.02 USDC, or 1 credit with a bearer token. Free integration testing: `sandbox=1`.", "security": [ {}, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/sandbox" }, { "$ref": "#/components/parameters/x402Probe" }, { "$ref": "#/components/parameters/paymentSignatureHeader" }, { "$ref": "#/components/parameters/xPaymentHeader" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional client idempotency key; paid responses are also idempotent per x402 payment authorization (same signed authorization -> cached response, never double-charged)" } ], "responses": { "200": { "description": "Rated wallets. When settled via per-call x402, the response includes a `paid` object (`price_paid_usdc`, `receipt`), and (x402 v2) a PAYMENT-RESPONSE header. Credit-lane calls get `paid: {credits_used, credits_remaining}` instead.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaderboardResponse" }, "example": { "ok": true, "computed_at": "2026-07-13", "window": "2026-06-12..2026-07-11 (30d) + out-of-sample month where noted", "method": "first-entry mirror, $5/trade, entry 0.10-0.90, no crypto-updown, min clip 10 shares; ROI net of 2c slippage; fee-inclusive column adds explicit 2026 taker fees (rate*p*(1-p))", "wallets": [ { "name": "S-Works", "verdict": "COPY", "roi_slippage_basis_pct": 11.3, "roi_fee_inclusive_pct": 9.2, "copied_trades": 132, "win_rate_pct": 62.9, "oos_validated": true, "reasons": [ "survived the out-of-sample month", "+9.2% fee-inclusive / +11.3% slippage-basis over 30d", "caveats: is a bot (iceberg execution ~24 clips per entry), copy-crowding in 102 of 319 markets" ] }, { "name": "cnyek", "verdict": "WATCH", "roi_slippage_basis_pct": 14.7, "roi_fee_inclusive_pct": 12.4, "copied_trades": 41, "oos_trades": 9, "win_rate_pct": 65.9, "oos_validated": true, "reasons": [ "+12.4% fee-inclusive over 41 in-sample copied trades", "survived OOS, but only 9 out-of-sample trades - OOS sample too small for COPY" ] }, { "name": "aenews2", "verdict": "WATCH", "roi_slippage_basis_pct": 1.9, "roi_fee_inclusive_pct": -0.9, "copied_trades": 62, "win_rate_pct": 56.5, "oos_validated": true, "reasons": [ "fee-fragile: +1.9% slippage-basis flips to -0.9% fee-inclusive in-sample", "+17.2% in the out-of-sample month" ] } ] } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "400": { "description": "Error (JSON, never HTML). 4xx errors are never charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (JSON, never HTML) - never charged; retry with the same payment authorization returns the cached response if the charge went through.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/red_list": { "get": { "operationId": "redListGet", "tags": [ "wallets" ], "summary": "Wallets that LOSE money for copiers (VETO)", "description": "Machine JSON of wallets a copier should refuse, same method and window as the leaderboard. Live calls are paid from the first request: HTTP 402 (x402). Price per call: $0.02 USDC, or 1 credit with a bearer token. Free integration testing: `sandbox=1`.", "security": [ {}, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/sandbox" }, { "$ref": "#/components/parameters/x402Probe" }, { "$ref": "#/components/parameters/paymentSignatureHeader" }, { "$ref": "#/components/parameters/xPaymentHeader" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional client idempotency key; paid responses are also idempotent per x402 payment authorization (same signed authorization -> cached response, never double-charged)" } ], "responses": { "200": { "description": "VETO-rated wallets. When settled via per-call x402, the response includes a `paid` object (`price_paid_usdc`, `receipt`), and (x402 v2) a PAYMENT-RESPONSE header. Credit-lane calls get `paid: {credits_used, credits_remaining}` instead.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedListResponse" }, "example": { "ok": true, "computed_at": "2026-07-13", "window": "2026-06-12..2026-07-11 (30d) + out-of-sample month where noted", "method": "first-entry mirror, $5/trade, entry 0.10-0.90, no crypto-updown, min clip 10 shares; ROI net of 2c slippage; fee-inclusive column adds explicit 2026 taker fees (rate*p*(1-p))", "wallets": [ { "name": "swisstony", "verdict": "VETO", "roi_slippage_basis_pct": -3.4, "roi_fee_inclusive_pct": -5.7, "copied_trades": 11649, "win_rate_pct": 54.8, "oos_validated": false, "reasons": [ "biggest wallet by volume on the tape and net-negative to copy", "-5.7% fee-inclusive (-3.4% before explicit fees) over 30d" ] }, { "name": "RN1", "verdict": "VETO", "roi_slippage_basis_pct": -2.5, "roi_fee_inclusive_pct": -4.8, "copied_trades": 7141, "win_rate_pct": 53.1, "oos_validated": false, "reasons": [ "-4.8% fee-inclusive copier ROI over 30d" ] } ] } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "400": { "description": "Error (JSON, never HTML). 4xx errors are never charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (JSON, never HTML) - never charged; retry with the same payment authorization returns the cached response if the charge went through.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/credits": { "get": { "operationId": "creditsBalance", "tags": [ "payment" ], "summary": "Pack info; with a bearer token, remaining balance", "description": "Without a token: returns the pack terms (price, credits, per-endpoint costs). With `Authorization: Bearer ` (issued by POST /api/credits): additionally returns the remaining balance and expiry for the paying wallet.", "security": [ {}, { "bearerAuth": [] } ], "responses": { "200": { "description": "Pack terms; plus `balance` and `expires` when a valid bearer token is presented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditsBalanceResponse" }, "example": { "ok": true, "balance": 483, "expires": "2027-07-13T00:00:00.000Z", "pack": { "usd": 5, "credits": 500, "valid_days": 365 }, "costs": { "preflight_trade": 1, "leaderboard": 1, "red_list": 1, "preflight_copy": 5 } } } } }, "401": { "description": "Error (JSON, never HTML). 4xx errors are never charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Error (JSON, never HTML). 4xx errors are never charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (JSON, never HTML) - never charged; retry with the same payment authorization returns the cached response if the charge went through.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "creditsPurchase", "tags": [ "payment" ], "summary": "Buy a credit pack (the fast lane)", "description": "One x402 payment of $5 USDC buys 500 credits plus a bearer token (format `tk__` - treat it as a secret; the last 5 tokens per wallet stay valid; credits are valid 12 months). Credit costs: preflight_trade / leaderboard / red_list = 1 credit; preflight_copy = 5 credits - half the per-call price versus x402. Bearer-authenticated calls respond in ~0.4s with no per-call on-chain settlement. An unpaid POST returns HTTP 402 with the payment requirements; retrying with the SAME payment authorization returns the cached response and never double-charges.", "security": [ {} ], "parameters": [ { "$ref": "#/components/parameters/x402Probe" }, { "$ref": "#/components/parameters/paymentSignatureHeader" }, { "$ref": "#/components/parameters/xPaymentHeader" } ], "responses": { "200": { "description": "Credit pack purchased. Store the token securely; it is shown in full only here.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditsPurchaseResponse" }, "example": { "ok": true, "token": "tk_0x1234abcd5678ef901234abcd5678ef901234abcd_s3cr3tS3cr3tS3cr3t", "wallet": "0x1234abcd5678ef901234abcd5678ef901234abcd", "credits_added": 500, "balance": 500, "expires": "2027-07-13T00:00:00.000Z", "note": "treat the token as a secret; use it as Authorization: Bearer on paid endpoints. Buying again with the same wallet adds credits and issues a fresh token (last 5 tokens stay valid).", "paid": { "price_paid_usdc": "5.00", "transaction": "0xabc123...", "network": "eip155:8453", "receipt": "https://basescan.org/tx/0xabc123..." } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "400": { "description": "Error (JSON, never HTML). 4xx errors are never charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (JSON, never HTML) - never charged; retry with the same payment authorization returns the cached response if the charge went through.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/redeem": { "post": { "operationId": "redeemPromoCode", "tags": [ "payment" ], "summary": "Redeem a promo code for free credits", "description": "Free - no payment involved. Redeems a promotional code for a bearer token preloaded with free credits. Codes are announced only in community posts (there is no public list). Rules: one redemption per wallet per code; each code has a global first-N-wallets cap and an expiry; promotional credits have no cash value and can be revoked on abuse or error - otherwise they behave like purchased credits (same bearer-token lane, same per-endpoint costs). The `wallet` value is any EVM-format address string used as identity only - no signature required, no funds move.", "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemRequest" }, "example": { "code": "EXAMPLECODE", "wallet": "0x1234abcd5678ef901234abcd5678ef901234abcd" } } } }, "responses": { "200": { "description": "Code redeemed. Store the token securely; it is shown in full only here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemResponse" }, "example": { "ok": true, "token": "tk_0x1234abcd5678ef901234abcd5678ef901234abcd_s3cr3tS3cr3tS3cr3t", "wallet": "0x1234abcd5678ef901234abcd5678ef901234abcd", "credits_added": 100, "balance": 100, "expires": "2027-07-15T00:00:00.000Z", "note": "promotional credits - no cash value, revocable on abuse; otherwise they behave like purchased credits" } } } }, "400": { "description": "Invalid request (missing or malformed code or wallet). Error JSON, never HTML; never charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown promo code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "This wallet already redeemed this code (one redemption per wallet per code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Code expired or its global first-N-wallets cap is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (JSON, never HTML).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/preflight_copy": { "get": { "operationId": "preflightCopyGet", "tags": [ "wallets" ], "summary": "COPY / WATCH / VETO verdict for copy-trading a wallet", "description": "Copy-trading profile with fee-inclusive copier ROI, win rate, entry-price buckets, category mix, iceberg signal and farming screen. The only parameter is `wallet` (alias `user`) - a 0x wallet address; usernames are not accepted. Method honesty: uses a fixed $5-entry / +2c-slippage simulation computed from TickTape's private identity-tagged trade tape (every fill of 5+ shares, recorded since December 2025; all market categories since mid-January 2026), NOT from the live Polymarket API - exact size-and-delay replay is not live. Explicit 2026 taker fees; crypto up/down markets excluded; rolling 90-day window recomputed nightly; in-sample verdicts capped at WATCH (COPY requires out-of-sample validation). Coverage rule: a wallet with 10+ first entries in the rolling 90-day window has a precomputed profile (tens of thousands of wallets after each nightly run) and answers sub-second; any other wallet returns HTTP 202 verdict QUEUED with a Retry-After header (always free, never settled, never debited) and, if it has tape activity, is typically ready in minutes (the response's retry_after_seconds tells you when to retry; worst case about an hour) - a wallet below the floor gets an explicit NO_COVERAGE profile. Covered responses include `data_through` and `next_refresh_at` (profiles refresh nightly by ~04:30 UTC) - do not re-purchase the same wallet before next_refresh_at. Full coverage rules incl. order-book archive scope: https://ticktape.cc/tech#coverage; live freshness: https://ticktape.cc/status.json. Live calls are paid from the first request: HTTP 402 (x402). Price per call: $0.10 USDC, or 5 credits with a bearer token. Free integration testing: `sandbox=1`.", "security": [ {}, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/copyWallet" }, { "$ref": "#/components/parameters/sandbox" }, { "$ref": "#/components/parameters/x402Probe" }, { "$ref": "#/components/parameters/paymentSignatureHeader" }, { "$ref": "#/components/parameters/xPaymentHeader" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional client idempotency key; paid responses are also idempotent per x402 payment authorization (same signed authorization -> cached response, never double-charged)" } ], "responses": { "200": { "description": "Wallet profile for a covered wallet (verdict QUEUED ships as HTTP 202, not 200). Paid x402 calls include a `paid` object and (v2) a PAYMENT-RESPONSE header; credit-lane calls get `paid: {credits_used: 5, credits_remaining}`.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreflightCopyResponse" }, "examples": { "covered": { "summary": "Covered wallet (sandbox shape)", "value": { "ok": true, "wallet": "0x00000000000000000000000000000000sandbox0", "name": "sandbox-whale", "window": { "from": "2026-04-14", "to": "2026-07-13", "days": 90 }, "n_first_entries": 214, "n_resolved": 180, "n_pending": 34, "win_rate_pct": 61.7, "roi_slippage_basis_pct": 10.8, "roi_fee_inclusive_pct": 8.6, "avg_entry_price": 0.44, "entry_price_buckets": { "0.0-0.1": 6, "0.1-0.2": 14, "0.2-0.3": 27, "0.3-0.4": 41, "0.4-0.5": 48, "0.5-0.6": 39, "0.6-0.7": 22, "0.7-0.8": 11, "0.8-0.9": 4, "0.9-1.0": 2 }, "category_mix_pct": { "sports": 62.1, "politics": 21.5, "other": 12.6, "crypto": 3.8 }, "clips_per_entry_avg": 3.2, "both_sides_pct": 1.9, "first_trade_at": "2026-04-15T09:12:44+00:00", "last_trade_at": "2026-07-13T18:03:10+00:00", "active_days": 71, "verdict": "WATCH", "reasons": [ "fee-inclusive copier ROI +8.6% (slippage-basis +10.8%) over 180 resolved first entries", "in-sample only - verdicts are capped at WATCH until the wallet survives an out-of-sample month" ], "computed_at": "2026-07-13T03:41:00+00:00", "method": "first-entry mirror computed from TickTape's identity-tagged RTDS tape (recorded since 2025-12-30), NOT from the live Polymarket API; $5 stake per first entry at whale price +$0.02 slippage, held to resolution; fee-inclusive ROI adds the 2026 taker fee rate*p*(1-p); crypto up/down window markets excluded; in-sample verdicts are capped at WATCH - COPY requires surviving an out-of-sample month" } } } } } }, "400": { "description": "Error (JSON, never HTML). 4xx errors are never charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "202": { "description": "QUEUED - wallet below coverage floor or not yet computed. Free (never charged - an attached payment is never settled and credits are never debited). Typically ready in minutes (the response's retry_after_seconds tells you when to retry); worst case about an hour. Covered wallets answer 200 sub-second.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "seconds until the profile is expected to be ready (mirrors the body's retry_after_seconds; typically minutes, worst case about an hour)" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreflightCopyResponse" }, "example": { "ok": true, "verdict": "QUEUED", "wallet": "0x1234567890abcdef1234567890abcdef12345678", "reasons": [ "below coverage floor or not yet computed - typically ready in minutes, worst case about an hour" ], "retry_after_seconds": 3600, "note": "this response is free - you were not charged. Retry the same call later; covered wallets answer sub-second." } } } }, "500": { "description": "Server error (JSON, never HTML) - never charged; retry with the same payment authorization returns the cached response if the charge went through.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "tk__", "description": "Credit-lane bearer token issued by POST /api/credits. Treat it as a secret. The last 5 tokens per wallet stay valid; credits are valid 12 months. Authenticated calls skip x402 settlement, respond in ~0.4s, and debit credits (preflight_trade / leaderboard / red_list = 1 credit; preflight_copy = 5 credits)." } }, "parameters": { "slug": { "name": "slug", "in": "query", "description": "Polymarket market or event slug. Full polymarket.com/event/ URLs are accepted. Required unless token_id is given.", "schema": { "type": "string" }, "example": "bitcoin-up-or-down-july-13-3pm-et" }, "outcome": { "name": "outcome", "in": "query", "description": "Outcome to price. For multi-outcome events pass a candidate name (partial match OK); a wrong outcome returns the candidate list. Required with slug for multi-outcome events.", "schema": { "type": "string" }, "example": "Up" }, "tokenId": { "name": "token_id", "in": "query", "description": "CLOB token id - alternative to slug + outcome.", "schema": { "type": "string" } }, "side": { "name": "side", "in": "query", "description": "Order side.", "schema": { "type": "string", "enum": [ "BUY", "SELL" ], "default": "BUY" } }, "usd": { "name": "usd", "in": "query", "description": "Order size in USD.", "schema": { "type": "number", "default": 100, "exclusiveMinimum": 0 } }, "maxSlippageC": { "name": "max_slippage_c", "in": "query", "description": "Threshold override: slippage in cents above which the verdict degrades from OK to CAUTION.", "schema": { "type": "number", "default": 1.0 } }, "vetoSlippageC": { "name": "veto_slippage_c", "in": "query", "description": "Threshold override: slippage in cents at which the verdict becomes VETO.", "schema": { "type": "number", "default": 3.0 } }, "maxBookAgeS": { "name": "max_book_age_s", "in": "query", "description": "Threshold override: maximum acceptable order-book age in seconds.", "schema": { "type": "number", "default": 60 } }, "sandbox": { "name": "sandbox", "in": "query", "description": "Set to 1 for a free deterministic example response. Never rate-limited, never charged. Use it to wire up parsing before paying.", "schema": { "type": "integer", "enum": [ 1 ] } }, "x402Probe": { "name": "x402_probe", "in": "query", "description": "Set to 1 to receive the HTTP 402 payment requirements for this call without paying. Free, always.", "schema": { "type": "integer", "enum": [ 1 ] } }, "paymentSignatureHeader": { "name": "PAYMENT-SIGNATURE", "in": "header", "description": "x402 v2 (primary): signed payment payload, base64-encoded. Send it when retrying a request that returned 402 with a PAYMENT-REQUIRED header. Reuse the same payment authorization on retries - the response is cached and never double-charged.", "schema": { "type": "string", "contentEncoding": "base64" } }, "xPaymentHeader": { "name": "X-PAYMENT", "in": "header", "description": "x402 v1 (also accepted): signed payment payload, base64-encoded, built from the 402 JSON body's accepts[]. Reuse the same payment authorization on retries.", "schema": { "type": "string", "contentEncoding": "base64" } }, "copyWallet": { "name": "wallet", "in": "query", "description": "Trader proxy wallet, 0x + 40 hex chars (alias: user=). The only parameter for preflight_copy - size/delay knobs do not exist; the verdict uses a fixed $5-entry / +2c-slippage simulation.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } }, "headers": { "PaymentResponse": { "description": "x402 v2: base64-encoded settlement confirmation for a paid call (facilitator: Coinbase CDP; settlement synchronous). Present only when the call was settled per-call via PAYMENT-SIGNATURE.", "schema": { "type": "string", "contentEncoding": "base64" } }, "PaymentRequired": { "description": "x402 v2 (primary): base64-encoded payment requirements. Decode, sign a payment authorization for exactly these terms (asset USDC on Base eip155:8453 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, payTo 0xb28bcb21a054ffeeb6ce62d0f1bb0175c022d2c6 - verify against https://ticktape.cc/llms.txt), then retry with the PAYMENT-SIGNATURE request header.", "schema": { "type": "string", "contentEncoding": "base64" } } }, "responses": { "PreflightTradeOk": { "description": "Verdict computed. When settled via per-call x402, the response includes a `paid` object (`price_paid_usdc`, `receipt`), and (x402 v2) a PAYMENT-RESPONSE header. Credit-lane calls get `paid: {credits_used, credits_remaining}` instead. With `sandbox=1`, top-level `sandbox` is true and the numbers are a deterministic example, not a live book.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreflightTradeResponse" }, "example": { "ok": true, "verdict": "CAUTION", "reasons": [ "slippage 1.6c per share - consider ~$130 instead", "order is 12.4% of visible depth" ], "market": { "slug": "example-market", "question": "Will the example team win?", "outcome": "Yes", "token_id": "0x1234..." }, "order": { "side": "BUY", "usd": 250 }, "numbers": { "best_price": 0.52, "expected_vwap": 0.536, "expected_slippage_cents": 1.6, "visible_depth_usd": 2012.5, "order_vs_depth_pct": 12.4, "taker_fee_usd": 1.87, "fee_drag_cents_per_share": 0.4, "fee_category": "standard", "safe_size_usd": 130, "book_age_seconds": 3 }, "meta": { "beta": true, "method": "deterministic arithmetic on the live CLOB book + Polymarket's published 2026 fee schedule (rate*p*(1-p)). No model, no prediction.", "thresholds": { "slippage_caution_cents": 1.0, "slippage_veto_cents": 3.0, "book_stale_veto_seconds": 60, "note": "defaults - override via max_slippage_c, veto_slippage_c, max_book_age_s" } }, "paid": { "price_paid_usdc": "0.02", "transaction": "0xabc123...", "network": "eip155:8453", "receipt": "https://basescan.org/tx/0xabc123..." } } } } }, "BadRequest": { "description": "Invalid or missing parameters. For multi-outcome events with a wrong `outcome`, the body includes the candidate list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "outcome 'Smith' not found for this event", "candidates": [ "John Smith Jr.", "Jane Smithson", "Alex Smythe" ] } } } }, "Unauthorized": { "description": "Missing, expired or revoked bearer token, or credits exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid or expired bearer token" } } } }, "PaymentRequired": { "description": "Live calls are paid from the first request (there is no free live tier), or `x402_probe=1` was set. Pay with x402 to proceed - dual-stack:\n\n- x402 v2 (primary): this response carries base64-encoded payment requirements in the PAYMENT-REQUIRED response header (network CAIP-2 `eip155:8453`). Retry the identical request with the PAYMENT-SIGNATURE request header. The paid 200 carries a PAYMENT-RESPONSE header.\n- x402 v1 (also accepted): the JSON body carries the same requirements in `accepts[]` (network `\"base\"`). Retry with the X-PAYMENT request header.\n\nAsset: USDC on Base only (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913). payTo: 0xb28bcb21a054ffeeb6ce62d0f1bb0175c022d2c6 - verify against https://ticktape.cc/llms.txt before signing. Per-call settlement is on-chain and adds ~2-5s (congestion tails longer); the credit lane (POST /api/credits + bearer token) responds in ~0.4s. Retrying with the SAME payment authorization returns the cached response and never double-charges. Facilitator: Coinbase CDP; settlement synchronous.", "headers": { "PAYMENT-REQUIRED": { "$ref": "#/components/headers/PaymentRequired" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequiredBody" }, "example": { "x402Version": 1, "error": "live calls are paid: $0.02 via x402 (v2 PAYMENT-SIGNATURE or v1 X-PAYMENT), or use credits (POST /api/credits). Free integration testing: ?sandbox=1", "accepts": [ { "scheme": "exact", "network": "base", "maxAmountRequired": "20000", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xb28bcb21a054ffeeb6ce62d0f1bb0175c022d2c6", "resource": "https://ticktape.cc/api/preflight_trade", "description": "TickTape preflight_trade - one call", "maxTimeoutSeconds": 60 } ] } } } } }, "schemas": { "PreflightTradeRequest": { "type": "object", "description": "Identify the market by slug + outcome, or by token_id.", "properties": { "slug": { "type": "string", "description": "Polymarket market or event slug; full event URLs accepted." }, "outcome": { "type": "string", "description": "Outcome to price (partial match OK for multi-outcome events)." }, "token_id": { "type": "string", "description": "CLOB token id - alternative to slug + outcome." }, "side": { "type": "string", "enum": [ "BUY", "SELL" ], "default": "BUY" }, "usd": { "type": "number", "default": 100, "exclusiveMinimum": 0, "description": "Order size in USD." }, "max_slippage_c": { "type": "number", "default": 1.0 }, "veto_slippage_c": { "type": "number", "default": 3.0 }, "max_book_age_s": { "type": "number", "default": 60 } } }, "PreflightTradeResponse": { "type": "object", "required": [ "ok", "verdict", "reasons", "market", "order", "numbers" ], "properties": { "ok": { "type": "boolean" }, "verdict": { "type": "string", "enum": [ "OK", "CAUTION", "VETO" ], "description": "Deterministic verdict on executing this order now, at this size, on this book. Not a prediction of the market outcome." }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Human- and machine-readable reasons, each carrying the number that triggered it." }, "market": { "type": "object", "properties": { "slug": { "type": [ "string", "null" ] }, "question": { "type": [ "string", "null" ] }, "outcome": { "type": [ "string", "null" ] }, "token_id": { "type": "string" } }, "description": "The market the verdict was computed for." }, "order": { "type": "object", "properties": { "side": { "type": "string", "enum": [ "BUY", "SELL" ] }, "usd": { "type": "number" } }, "description": "The order as understood by the endpoint." }, "numbers": { "type": "object", "properties": { "best_price": { "type": "number", "description": "Best available price on the relevant side of the book." }, "expected_vwap": { "type": "number", "description": "Volume-weighted average fill price for the requested size." }, "expected_slippage_cents": { "type": "number", "description": "expected_vwap minus best_price, in cents per share." }, "visible_depth_usd": { "type": "number", "description": "Visible depth on the relevant side, in USD." }, "order_vs_depth_pct": { "type": "number", "description": "Order size as a percentage of visible depth." }, "taker_fee_usd": { "type": "number", "description": "Total taker fee for this order under the 2026 schedule." }, "fee_drag_cents_per_share": { "type": "number", "description": "Taker fee expressed in cents per share (rate * p * (1-p))." }, "fee_category": { "type": "string", "description": "Fee schedule category applied to this market." }, "safe_size_usd": { "type": "number", "description": "Largest order size that would still pass the OK thresholds on this book." }, "book_age_seconds": { "type": "number", "description": "Age of the order-book snapshot used." } } }, "meta": { "type": "object", "description": "Present on live-book responses (absent on sandbox examples).", "properties": { "beta": { "type": "boolean" }, "method": { "type": "string" }, "for_whom": { "type": "string" }, "thresholds": { "type": "object", "properties": { "slippage_caution_cents": { "type": "number" }, "slippage_veto_cents": { "type": "number" }, "depth_caution_fraction": { "type": "number" }, "book_stale_veto_seconds": { "type": "number" }, "note": { "type": "string" } }, "description": "Thresholds used for this verdict - defaults, or the caller's max_slippage_c / veto_slippage_c / max_book_age_s overrides." } } }, "sandbox": { "type": "boolean", "description": "True when the response is the free deterministic sandbox example." }, "note": { "type": "string" }, "paid": { "$ref": "#/components/schemas/Paid" } } }, "WalletRating": { "type": "object", "required": [ "name", "verdict", "roi_fee_inclusive_pct", "reasons" ], "properties": { "name": { "type": "string", "description": "Polymarket display name (public pseudonym)." }, "verdict": { "type": "string", "enum": [ "COPY", "WATCH", "VETO" ] }, "roi_slippage_basis_pct": { "type": "number", "description": "Simulated copier ROI over the window net of the 2c slippage floor, before explicit taker fees." }, "roi_fee_inclusive_pct": { "type": "number", "description": "Simulated copier ROI over the window with explicit 2026 taker fees, first-entry mirror $5/trade, 2c slippage." }, "copied_trades": { "type": "integer", "description": "Number of mirrored trades in the in-sample window (the 30d window in `window`)." }, "oos_trades": { "type": "integer", "description": "Number of mirrored trades in the out-of-sample month. Present when the OOS sample size drove the verdict; distinct from copied_trades, which counts the in-sample window." }, "win_rate_pct": { "type": "number", "description": "Share of mirrored in-sample trades that won, in percent." }, "oos_validated": { "type": "boolean", "description": "True if the wallet survived the out-of-sample month." }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Reasons and caveats behind the verdict, each carrying its numbers." } } }, "LeaderboardResponse": { "type": "object", "required": [ "ok", "computed_at", "window", "method", "wallets" ], "properties": { "ok": { "type": "boolean" }, "computed_at": { "type": "string", "format": "date" }, "window": { "type": "string", "description": "Human-readable audit window, e.g. \"2026-06-12..2026-07-11 (30d) + out-of-sample month where noted\"." }, "method": { "type": "string" }, "universe": { "type": "string", "description": "The selection funnel behind the ratings." }, "note": { "type": "string" }, "wallets": { "type": "array", "items": { "$ref": "#/components/schemas/WalletRating" }, "description": "Wallets rated COPY or WATCH." }, "paid": { "$ref": "#/components/schemas/Paid" } } }, "RedListResponse": { "type": "object", "required": [ "ok", "computed_at", "window", "method", "wallets" ], "properties": { "ok": { "type": "boolean" }, "computed_at": { "type": "string", "format": "date" }, "window": { "type": "string", "description": "Human-readable audit window, e.g. \"2026-06-12..2026-07-11 (30d) + out-of-sample month where noted\"." }, "method": { "type": "string" }, "universe": { "type": "string", "description": "The selection funnel behind the ratings." }, "note": { "type": "string" }, "wallets": { "type": "array", "items": { "$ref": "#/components/schemas/WalletRating" }, "description": "Wallets rated VETO - copying them lost money for the simulated copier." }, "paid": { "$ref": "#/components/schemas/Paid" } } }, "CreditsBalanceResponse": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" }, "balance": { "type": "integer", "description": "Remaining credits for the wallet behind the bearer token. Present only with a valid token." }, "expires": { "type": "string", "format": "date-time", "description": "Credit expiry (12 months from purchase). Present only with a valid token." }, "pack": { "type": "object", "description": "Pack terms: {usd, credits, valid_days}." }, "costs": { "type": "object", "description": "Per-endpoint credit costs: preflight_trade / leaderboard / red_list = 1; preflight_copy = 5." } } }, "CreditsPurchaseResponse": { "type": "object", "required": [ "ok", "token", "wallet", "credits_added", "balance" ], "properties": { "ok": { "type": "boolean" }, "token": { "type": "string", "description": "Bearer token, format tk__. Treat as a secret; shown in full only in this response. The last 5 tokens per wallet stay valid." }, "wallet": { "type": "string", "description": "Paying wallet the credits are keyed to." }, "credits_added": { "type": "integer", "description": "500 per $5 pack." }, "balance": { "type": "integer", "description": "Total credits now on the wallet." }, "expires": { "type": "string", "format": "date-time", "description": "Credits are valid 12 months from purchase." }, "note": { "type": "string" }, "paid": { "$ref": "#/components/schemas/Paid" } } }, "RedeemRequest": { "type": "object", "required": [ "code", "wallet" ], "properties": { "code": { "type": "string", "description": "Promo code, as announced in a community post. There is no public list of codes." }, "wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "EVM-format address string used as identity only - no signature required, no funds move. One redemption per wallet per code." } } }, "RedeemResponse": { "type": "object", "required": [ "ok", "token", "wallet", "credits_added", "balance" ], "properties": { "ok": { "type": "boolean" }, "token": { "type": "string", "description": "Bearer token, format tk__. Treat as a secret; shown in full only in this response." }, "wallet": { "type": "string", "description": "The wallet string the promotional credits are keyed to." }, "credits_added": { "type": "integer", "description": "Free credits granted by the code." }, "balance": { "type": "integer", "description": "Total credits now on the wallet." }, "expires": { "type": "string", "format": "date-time", "description": "Credit expiry." }, "note": { "type": "string", "description": "Promotional credits have no cash value and can be revoked on abuse or error; otherwise they behave like purchased credits." } } }, "Paid": { "type": "object", "description": "Payment record attached to paid responses. Per-call x402 settlement: {price_paid_usdc, transaction, network, receipt}. Credit-lane (bearer token) calls: {credits_used, credits_remaining}. Absent on sandbox and free QUEUED responses.", "properties": { "price_paid_usdc": { "type": "string", "description": "USDC actually settled for this call, as a decimal string (e.g. \"0.02\")." }, "transaction": { "type": "string", "description": "On-chain settlement transaction hash." }, "network": { "type": "string", "description": "CAIP-2 network id, eip155:8453 (Base)." }, "receipt": { "type": [ "string", "null" ], "format": "uri", "description": "Basescan transaction link for the on-chain settlement." }, "credits_used": { "type": "integer", "description": "Credits debited for this call (credit-lane only)." }, "credits_remaining": { "type": "integer", "description": "Credits left on the wallet after this call (credit-lane only)." } } }, "X402PaymentRequiredBody": { "type": "object", "description": "x402 v1-style payment requirements (the v2 equivalent is base64-encoded in the PAYMENT-REQUIRED response header).", "required": [ "accepts" ], "properties": { "x402Version": { "type": "integer" }, "error": { "type": "string" }, "accepts": { "type": "array", "items": { "type": "object", "required": [ "scheme", "network", "maxAmountRequired", "asset", "payTo", "resource" ], "properties": { "scheme": { "type": "string", "const": "exact" }, "network": { "type": "string", "description": "\"base\" in v1 payloads; CAIP-2 eip155:8453 in v2 headers." }, "maxAmountRequired": { "type": "string", "description": "Atomic USDC units (6 decimals): \"20000\" = $0.02, \"100000\" = $0.10, \"5000000\" = $5." }, "asset": { "type": "string", "description": "USDC on Base: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913. Refuse anything else." }, "payTo": { "type": "string", "description": "Must equal 0xb28bcb21a054ffeeb6ce62d0f1bb0175c022d2c6 - verify against https://ticktape.cc/llms.txt before signing." }, "resource": { "type": "string", "format": "uri", "description": "Must be under https://ticktape.cc/ - never pay for resources elsewhere." }, "description": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer" } } } } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "candidates": { "type": "array", "items": { "type": "string" }, "description": "For multi-outcome events: valid outcome names when the requested outcome was not found." } } }, "PreflightCopyResponse": { "type": "object", "description": "Copy-trading profile for one wallet, computed from TickTape's identity-tagged tape (Dec 2025 onward), rolling 90-day window, recomputed nightly. QUEUED responses ship as HTTP 202 with a Retry-After header, carry only verdict/wallet/reasons/retry_after_seconds/note and are always free.", "required": [ "ok", "verdict" ], "properties": { "ok": { "type": "boolean" }, "verdict": { "type": "string", "enum": [ "COPY", "WATCH", "VETO", "NO_COVERAGE", "QUEUED" ], "description": "COPY only for out-of-sample-validated wallets; in-sample verdicts are capped at WATCH. VETO = negative fee-inclusive copier ROI or both-sides farming pattern. NO_COVERAGE = below the 10-first-entry floor. QUEUED = not computed yet (HTTP 202 + Retry-After, free) - typically ready in minutes (retry after retry_after_seconds), worst case about an hour." }, "reasons": { "type": "array", "items": { "type": "string" } }, "wallet": { "type": "string" }, "name": { "type": [ "string", "null" ], "description": "last pseudonym seen on the tape" }, "window": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "days": { "type": "integer" } } }, "n_first_entries": { "type": "integer", "description": "distinct (market, outcome) first BUY entries in the window; crypto up/down markets excluded" }, "n_resolved": { "type": "integer" }, "n_pending": { "type": "integer" }, "win_rate_pct": { "type": [ "number", "null" ] }, "roi_slippage_basis_pct": { "type": [ "number", "null" ], "description": "$5/entry at whale price +2c slippage, held to resolution" }, "roi_fee_inclusive_pct": { "type": [ "number", "null" ], "description": "slippage basis minus explicit 2026 taker fees (rate*p*(1-p))" }, "avg_entry_price": { "type": [ "number", "null" ] }, "entry_price_buckets": { "type": "object", "additionalProperties": { "type": "integer" } }, "category_mix_pct": { "type": "object", "additionalProperties": { "type": "number" } }, "clips_per_entry_avg": { "type": "number", "description": "iceberg signal - how many fills the wallet splits one entry into" }, "both_sides_pct": { "type": "number", "description": "share of markets where the wallet bought BOTH outcomes (farming smell)" }, "first_trade_at": { "type": [ "string", "null" ] }, "last_trade_at": { "type": [ "string", "null" ] }, "active_days": { "type": "integer" }, "retry_after_seconds": { "type": "integer", "description": "QUEUED only" }, "computed_at": { "type": "string" }, "method": { "type": "string" }, "paid": { "$ref": "#/components/schemas/Paid" } } } } } }