@0xinsider/mcp

@0xinsider/mcp

Official CLI and MCP server for 0xinsider — Polymarket analytics & infrastructure for sports and esports markets, for AI agents and scripts.

Gives your AI agent and terminal scripts the same Polymarket data the tools run on: wallet grades on settled P&L, large trades, which side the profitable wallets hold on a market, daily picks on a public record, and suspicious trades.

CLI and MCP entry points

Install the official CLI globally when you want a stable terminal command:

npm install --global @0xinsider/mcp
0xinsider --help

On macOS or Linux with Homebrew, the official tap installs the same package and both commands (the formula is named oxinsider because Homebrew formula names cannot start with a digit):

brew install 0xinsider/tap/oxinsider
0xinsider --help

The package also exposes 0xinsider-mcp as an explicit alias. Both commands run the same CLI, and npx -y @0xinsider/mcp remains the zero-install path.

The same CLI is published under the unscoped name 0xinsider, so npx 0xinsider --help and npm install --global 0xinsider work too.

For Python, pip install 0xinsider installs the official Python SDK (0xinsider-python, import oxinsider). For Go programs, the official Go SDK (github.com/0xinsider/0xinsider-go) is generated from the same public OpenAPI contract the CLI and MCP tools read, as are the official Rust client (0xinsider-rust, crate oxinsider) and the Node.js and TypeScript client (0xinsider-node, @0xinsider/sdk).

Pick of the Day

get_pick_of_the_day and its archive use the account's published access. Pro opens five selections in total: the designated free selection plus the first four other selections in publication order. Max opens every available daily selection, up to twenty. Use each stable pick_id and preserve the returned order.

For an automated entry from a current pick, require a matching, unexpired returned authorization and honor its maximum price and any stricter local limits. Quote a current executable book for the actual stake. An authorization does not guarantee a fill.

Upgrade to 3.5.0

Version 3.5 adds ten tools for /api/v1 reads that had none: get_trader_context, get_trader_categories, get_trader_grade_at, get_market_holders, get_market_candles, the Pro or Max combo tools get_combo_fills, get_combos_summary and get_combo, and get_large_trade_counterparty_executions and get_large_trade_counterparty_makers, which page past the counterparty page get_large_trade embeds. get_trader takes max_age_s, a freshness ceiling that fails with reason freshness_ceiling_unsatisfied instead of answering with older data, and get_market_snapshot takes expand: ["trust"]. Existing tools keep their names, inputs and results.

Version 3 replaces get_pre_game_sides, get_pre_game_side_observations, get_sports_edge_signals, and get_sports_edge_observations with one get_edge_hunter tool. All views require Max.

The default view: "board" preserves the full quoted board with a 48-hour horizon and at most 30 rows. view: "signals" restores complete ranked records, token IDs, category/grade/horizon filters, cursor pagination, category evidence and provenance. view: "observations" requires cohort: "wider_holder" | "in_play" | "emerging_pile" and preserves the full observation rows, price marks, source clocks, snapshot, degraded state and per-sport funnel. Advanced page size defaults to 20 and clamps to 1..100. Signals horizon defaults to 12; observations use the fixed source universe. The tool retains every advanced envelope field beside REST meta. REST/SDK advanced views support ETag/304; the default board has no ETag. Parameters for another view return 400. Price marks are market midpoints, not wallet entry costs; volume is shares.

Version 3.2 adds common selection arguments to every view: kind, sports, leagues, market_types, condition_ids, event_slugs, series_slugs and legacy category. Supply arrays of 1..100 values; OR within an array and AND across axes. category: "NFL" selects Football, while leagues: ["nfl"] selects NFL only. Board min_grade and limit are configurable, with the same B/30 defaults. Selected reads force strict query validation and require the normalized selection echo. All public views read fresh warmed generations; absent selected metadata sidecars return 503 warming rather than silently broadening the result.

Rows add nullable market_context with nullable league, series_slug, market_type and metadata_updated_at. Use those frozen provider identities for exact selections; the timestamp is the local canonical metadata writer clock. Default board MCP output keeps rows, as_of, ranking_source and directional_source beside meta and optional selection. Advanced output keeps the complete list envelope and its provenance in meta. Observation funnel accounting describes the source generation/category, not selected input supply.

Version 3.3 adds both nullable outcome token_id values and the full board signal's nullable backed token_id, frozen ranked_at and existing aggregate category_skill. The ranking timestamp copies signal_created_at; quote and category-evidence clocks remain independent. The same data producer serves the Max website board. Admission, ordering, the existing tools and the three views stay compatible. Nullable quotes remain unavailable rather than becoming zero.

The four legacy REST URLs remain HTTP 410 with code and reason endpoint_retired. Migrate to the matching Edge Hunter view and restart pagination at page one.

Two ways to connect

• Remote HTTP (no install) — POST https://api.0xinsider.com/api/v1/mcp with Authorization: Bearer oxi_sk_live_.... Implements the MCP Streamable HTTP transport (protocolVersion 2025-11-25). Works with MCP clients that speak HTTP and can send headers. initialize, ping and tools/list need no key, so a client can show the catalog first; tools/call without a credential answers HTTP 401 with a WWW-Authenticate challenge naming the RFC 9728 document at /.well-known/oauth-protected-resource/api/v1/mcp. Clients that implement the MCP authorization spec follow it to the OAuth 2.1 authorization server (PKCE S256, dynamic client registration), sign the user in and send the resulting access token instead of an API key; see https://0xinsider.com/auth.md. A key in a ?token= query parameter is rejected on every route, /api/v1/mcp included, with 401 invalid_api_key and error.reason api_key_in_query, because URL secrets leak through shell history, browser history, proxy logs, and crash reports. A client that can only take a URL runs the stdio package with the key in its environment. Remote and stdio use the same read-only public V1 tool catalog, rate limits, and billing.
• Documentation server (no install, no key) — https://docs.0xinsider.com/mcp searches and reads the developer documentation over MCP. Add it beside the product server so an agent can look up how an endpoint works before it calls a tool.
• Stdio (this npm package) — run npx -y @0xinsider/mcp locally for Claude Code / Cursor / Codex / Gemini CLI. Best when the client can launch a child process and you prefer to keep the API key out of URLs.

Both remote HTTP and stdio expose 55 read-only tools from the Rust canonical registry.

• get_leaderboard — Get Trader Leaderboard (group: traders)
• get_trader — Get trader (group: traders)
• batch_get_traders — Batch traders (group: traders)
• get_large_trades — List large trades (group: large_trades)
• get_large_trade — Get large trade (group: large_trades)
• get_large_trades_history — Replay historical large trades (group: large_trades)
• get_whale_trades — List Whale Trades (group: large_trades)
• get_whale_trade — Get Whale Trade (group: large_trades)
• get_whale_trades_history — Replay Historical Whale Trades (group: large_trades)
• get_edge_hunter — Get Edge Hunter (group: markets)
• list_games — List covered games (group: games)
• get_game — Get one game (group: games)
• get_market_flow — Get market flow (group: markets)
• batch_get_market_flow — Batch market flow (group: markets)
• get_market_intel — Get Market Intelligence (group: markets)
• batch_get_market_intel — Batch Market Intelligence (group: markets)
• get_sharp_money_flows — List sharp-money flows (group: markets)
• get_smart_money_flows — List Smart-Money Flows (group: markets)
• get_market_snapshot — Get Market Snapshot (group: markets)
• get_suspicious_trades — Get suspicious trades (group: suspicious_trades)
• get_suspicious_trade — Get suspicious trade (group: suspicious_trades)
• get_insider_radar — Get Insider Radar Flags (group: suspicious_trades)
• get_insider_radar_flag — Get Insider Radar Flag (group: suspicious_trades)
• get_positions — List Current Positions (group: traders)
• get_position_timeline — Get Position Timeline (group: traders)
• get_position_timeline_by_id — Get Position Timeline By Trader ID (group: traders)
• search_markets — Search Markets (group: markets)
• search_content — Search Editorial Content (group: content)
• explore_markets — Explore Markets (group: markets)
• get_event_replay_since — Replay Public Events (group: large_trades)
• list_webhooks — List Webhook Endpoints (group: webhooks)
• get_webhook — Get Webhook Endpoint (group: webhooks)
• get_daily_report_snapshot — Get Daily Report Snapshot (group: reports)
• get_weekly_report_snapshot — Get Weekly Report Snapshot (group: reports)
• get_monthly_report_snapshot — Get Monthly Report Snapshot (group: reports)
• get_report — Get Report Snapshot (group: reports)
• get_trader_export_snapshot — Get Trader Export Snapshot (group: traders)
• get_coverage — Get coverage (group: platforms)
• get_platforms — Get Platform Capability Matrix (group: platforms)
• get_large_positions — List Large Positions (group: markets)
• get_trending_wallets — List Trending Wallets (group: traders)
• get_trader_pnl — Get Trader P&L Time Series (group: traders)
• get_pick_of_the_day — Get Pick of the Day (group: picks)
• get_pick_of_the_day_ledger_entry — Get Pick of the Day Proof (group: picks)
• get_pick_of_the_day_archive — Get Pick of the Day Archive (group: picks)
• get_trader_context — Get trader context (group: traders)
• get_trader_categories — Get trader category records (group: traders)
• get_trader_grade_at — Get trader grade at an instant (group: traders)
• get_market_holders — Get market holders (group: markets)
• get_market_candles — Get market price candles (group: markets)
• get_combo_fills — Get combo fills (group: combos)
• get_combos_summary — Get live combo count (group: combos)
• get_combo — Get combo (group: combos)
• get_large_trade_counterparty_executions — Get large trade counterparty executions (group: large_trades)
• get_large_trade_counterparty_makers — Get large trade counterparty makers (group: large_trades)

The canonical suspicious-trade tools are get_suspicious_trades and get_suspicious_trade; the older get_insider_radar and get_insider_radar_flag stay live as deprecated aliases on the deprecated /api/v1/insider-radar paths, and get_smart_money_flows stays live as a deprecated alias of get_sharp_money_flows.

Quick Start

Claude Code

npx -y @0xinsider/mcp init

init reads the key without echoing it. For non-interactive setup, set OXINSIDER_API_KEY in the process environment or pipe the key on stdin. Do not pass the key as a command-line argument.

init adds the server to ~/.claude.json, where Claude Code keeps user-scoped MCP servers, and moves an entry an earlier version left in ~/.claude/settings.json, which Claude Code does not read for MCP servers. Open a new Claude Code session, then run claude mcp list to confirm.

Or add it by hand to the top-level mcpServers object in ~/.claude.json:

{
  "mcpServers": {
    "0xinsider": {
      "command": "npx",
      "args": ["-y", "@0xinsider/mcp"],
      "env": {
        "OXINSIDER_API_KEY": "oxi_sk_live_..."
      }
    }
  }
}

Cursor

npx -y @0xinsider/mcp init can also configure Cursor automatically when its local config directory is present.

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "0xinsider": {
      "command": "npx",
      "args": ["-y", "@0xinsider/mcp"],
      "env": {
        "OXINSIDER_API_KEY": "oxi_sk_live_..."
      }
    }
  }
}

Codex

npx -y @0xinsider/mcp init can also configure Codex automatically.

Or add this to ~/.codex/config.toml:

[mcp_servers."0xinsider"]
command = "npx"
args = ["-y", "@0xinsider/mcp"]

[mcp_servers."0xinsider".env]
OXINSIDER_API_KEY = "oxi_sk_live_..."

Gemini CLI

npx -y @0xinsider/mcp init detects Gemini CLI when the gemini command is installed and prints a manual config template.

Or add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "0xinsider": {
      "command": "npx",
      "args": ["-y", "@0xinsider/mcp"],
      "env": {
        "OXINSIDER_API_KEY": "oxi_sk_live_..."
      }
    }
  }
}

Other MCP Clients

Any client that supports stdio transport:

Set OXINSIDER_API_KEY in the process environment before starting the stdio server. Do not pass the key as a command-line argument.

The stdio server answers each client in the protocol revision it opens with: the 2026-07-28 revision, or, as before, an initialize handshake at any revision from 2024-10-07 through 2025-11-25.

Need the command list? Run:

npx -y @0xinsider/mcp --help

API Key

Get your API key at 0xinsider.com/developers. Requires a Pro subscription.

Check access after a lapse

The CLI keeps account diagnostics available when paid data access lapses:

0xinsider whoami --json
0xinsider usage --json

whoami calls GET /api/v1/me and reports credential_status plus entitlement.paid_data_access and entitlement.recovery_action. A lapsed credential reports paid_data_access: "lapsed" and recovery_action: "renew_subscription"; usage still reports the caller's rate-limit, daily-usage and monthly-quota state. Use those fields to choose subscription renewal or credential recovery before retrying a paid data call.

Security

init never prints the API key. If an older version wrote the key to recorded terminal output, rotate the key before you use the new configuration.

Tools

Explore result metadata

explore_markets includes the API's meta object beside its data, facets, and pagination fields. It preserves the request ID, cache flag, and any other metadata the API sends. An unknown cache age stays absent. The tool's arguments and existing page fields keep their meanings.

Result text

A successful tool call returns its JSON as compact text, with no indentation, since 2.14.1. The remote endpoint sends the same compact text. The fields and values are unchanged, so any JSON parser reads the text as before.

Resources

Prompts

Example Usage

Once configured, ask your AI agent:

• "Who are the top prediction market traders right now?"
• "What are whales buying in crypto markets?"
• "Analyze trader 0x1234... — is their strategy worth following?"
• "Analyze trader swisstony — is their strategy worth following?"
• "Are there any suspicious trading patterns on the Trump election market?"
• "Generate a sharp money report for AI markets"

Environment Variables

Rate Limits

100 requests per minute per user. Pro includes 500,000 and Max includes 2,000,000 authenticated requests per UTC calendar month. Over the plan's included requests, pay as you go bills USD 0.20 per 1,000, up to four times the included allowance, when it is turned on at https://0xinsider.com/developers; without it, and at that ceiling with it, the next request answers 429 with error.reason monthly_quota_exceeded until the month resets (from October 1, 2026). The server returns actionable error messages when limits are hit, and every authenticated response carries X-Monthly-Quota-Limit, X-Monthly-Quota-Remaining and X-Monthly-Quota-Reset.

Timeouts

Every API request has a 15 s deadline covering headers and the complete response body; a request that misses it returns Error (request_timeout): ... and structuredContent.error.code: "request_timeout" to the tool caller. Other network or body-read failures return transport_error. If headers arrived, these errors retain the received HTTP status, request ID, and validated retry delay; before headers, status is absent. The original cause stays on the local ApiError and is not rendered into tool output. Neither failure retries automatically, and a POST whose response was lost may have committed.

MCP request cancellation and connection closure cancel every tool and resource HTTP read, including response-body consumption. Caller cancellation returns the local error code request_cancelled, even if the caller's reason is a TimeoutError; only the server's own deadline produces request_timeout. If headers arrived, cancellation retains the same HTTP status, request ID, and validated retry delay. Cancellation stops this client's HTTP work, but does not guarantee remote work stopped or roll back a POST that already committed. No automatic retry is made.

Both documentation resources (oxinsider://docs/api and oxinsider://docs/agents) have the same 15 s deadline and caller cancellation. Their error text distinguishes request_cancelled from request_timeout.

The bundled TypeScript SDK preserves a caller's exact cancellation reason on API calls, including a caller-owned TimeoutError. Only its own deadline produces RequestTimeoutError; cancellation also stops API body reads and retry backoff.

Its export download helpers cancel object responses they cannot return and wait up to 2 seconds for cleanup, preserving the original failure and any cleanup diagnostic in its cause. They stream successful downloads and retain their existing checksum defaults and caller cancellation options. Once a response is returned, its consumer owns reading or cancelling the body.

The agents.md instructions fetch at startup has a 3 s deadline and is skipped, not fatal, when it misses. A fully read non-JSON upstream failure (an HTML 502 from the edge, a text 429) keeps its HTTP status and existing invalid_response classification.

MCP error text and structuredContent.error.retry_after_seconds use the same validated Retry-After delay. Whole non-negative seconds up to Number.MAX_SAFE_INTEGER and the three HTTP-date formats are accepted. Date delays are measured when headers arrive, rounded upward to whole seconds, and clamped to zero for a past date. Missing, malformed, negative, fractional, or unsafe numeric values provide no retry instruction. A REST retry_at is preserved separately. The stdio client never retries a tool request automatically.

Development checks

Run npm run check-types, npm run lint, and npm run build before packaging. Strict collection indexing and optional-field checks guard missing entries and omit absent request options while preserving CLI output, MCP payloads, and caller-owned abort reasons.

License

MIT

Product CLI in 2.x

Version 2.x requires Node.js 22 or newer. It preserves 0xinsider, 0xinsider-mcp, init, serve, and no-argument stdio MCP startup. Users on an older Node runtime can keep @0xinsider/mcp@1.3.1 while upgrading Node.

0xinsider login
0xinsider whoami --json
0xinsider markets search "basketball" --json | jq '.data'
0xinsider markets explore --limit 10 --query category=basketball --json
0xinsider market snapshot <condition-id> --json
0xinsider market flow <condition-id> --json
0xinsider traders get <wallet-address> --json
0xinsider traders pnl <wallet-address> --json
0xinsider leaderboard list --json
0xinsider whales list --json
0xinsider positions list --json
0xinsider pick today --json
0xinsider reports daily --json
0xinsider usage --json
0xinsider logout

login prints a verification URL and code on stderr. Open the URL, sign in, check the code, account and requested read/usage scopes, then explicitly approve or deny. The terminal waits without asking for your password or developer key. Denial, expiry and interruption stop login; impatient polling honors the server's persistent backoff. No browser is opened automatically, so headless terminals use the same flow. If you interrupt after approval, review connected applications in Developers and revoke any connection you do not need.

A stored session uses $XDG_CONFIG_HOME/0xinsider/cli/session.json, or ~/.config/0xinsider/cli/session.json when XDG_CONFIG_HOME is unset. Override its directory with OXINSIDER_CONFIG_DIR. The directory must be owned by you with mode 0700; the file uses 0600, flushed writes and atomic replacement. Stored sessions currently support macOS/Linux; Windows users can use an environment credential. Login and logout refuse an existing session.lock. Data reads wait up to 10 seconds for its owner, within the request deadline, then reread the session before refreshing. They never steal the lock. After an unclean process termination, inspect its owner.json and remove the stale lock only after confirming that process has stopped.

OXINSIDER_API_KEY takes precedence for data commands. It is never persisted or revoked by logout. Login refuses to replace an existing stored session: logout first to change accounts. Refresh rotates only the stored CLI grant. Logout revokes its refresh token before removing the file, including after subscription lapse or access-token expiry; a failed remote revocation keeps the local session available for retry. Stored sessions are bound to their API origin. Product commands accept only the production API or loopback development origins through OXINSIDER_API_URL; use a separate config directory for local development. Existing MCP startup continues to use its environment credential.

JSON is the default even in a terminal. A single request preserves the SDK/API envelope, freshness fields, request IDs and opaque cursors. --table explicitly selects a tab-separated view for list results, with metadata on stderr; object responses remain readable JSON. Neither view rounds numeric values.

One page is fetched by default. --pages N follows at most 1–100 pages and returns one cli_pages document containing each full page and complete. If more data remains, it exits 8 and supplies next_cursor; this is an incomplete bounded traversal, not a complete result. A failed traversal exits nonzero, preserves already fetched pages in an incomplete JSON result, and prints its resume point on stderr. --query name=value supplies API filters; reports daily defaults to the current UTC date; override it with --query date=YYYY-MM-DD. --path name=value supplies path parameters for api call <operation-id>. That escape hatch permits registered JSON GET operations only; mutations, webhook administration, exports, streams and Markdown routes are excluded.

Stored-session reads obtain current credentials for each page. A 401 permits one refresh/reload and one retry of that same page; earlier pages are preserved. A rotated token from another process is reused without replaying its consumed refresh token. Environment keys are not refreshed. Revocation and insufficient scope remain failures. A subscription lapse still fails paid data reads, while whoami and usage remain available so the CLI can show the recovery state.

--timeout-ms bounds each request including lock waits, refresh and SDK retries (default 30000, maximum 300000). --retries is 0–3 (default 2); the SDK honors Retry-After within that deadline. Ctrl-C cancels requests and polling. Stdout contains results; progress and failures use stderr. --help, --version and completions bash|zsh|fish work offline without a credential. Load generated completion text using your shell's normal completion configuration.

Network failures before headers and while reading a response body both exit 7. Malformed JSON or response schemas remain exit 6; caller interruption remains 130. OAuth body timeouts use the same request deadline and device-poll network backoff. Registration, refresh and revocation gain no automatic retry: a lost response can leave the server outcome unknown, and stored sessions retain their existing recovery rules. The CLI prints the classified message, without response bodies or nested transport causes.

The build compiles the existing sdk/src owner into dist/sdk; it does not maintain a second HTTP transport or operation registry. No unpublished workspace dependency is required by the installed package.