polymarket-predictradar-data-layer-skills

Shared Polymarket and prediction-market data access layer. Use this skill whenever another skill or task needs trader positions, trade history, market metada...

Security Scan

The skill is broadly what it says (a Polymarket/PredicTradar data layer) but there are multiple mismatches and risky implementation choices (undeclared env vars, local execution, disk writes, and insecure TLS) that the installer should understand before using it.

Purpose & Capability

The package implements a prediction-market data layer (mcp-client, queries, gamma-client, smartmoney) which matches the declared purpose. However the manifest declared 'required env vars: none' while the code reads MCP_URL and MCP_API_KEY (mcp-client.js) and also inspects HTTPS_PROXY/HTTP_PROXY (proxy-config.js). It executes platform tools (scutil, python3) to detect proxies even though no binaries were declared as required. These undeclared runtime dependencies and env var hooks are inconsistent with the skill metadata.

Instruction Scope

SKILL.md instructs usage of the MCP wrapper, which is consistent. But the included scripts do extra things beyond simple read-only requests: they create and manage local cache files under scripts/cache (cache.js), run a cache warm-up sequence that will perform many queries (init.js, daily-report.js), and detect system proxy settings by executing scutil and python3 (proxy-config.js). Those operations read/write local filesystem state and run local commands rather than only performing remote read-only API calls; the runtime instructions do not fully call these out.

Install Mechanism

There is no install spec (instruction-only), which reduces supply-chain risk. But the skill includes many code files that will run inside the agent environment; no build/install step is required and files will execute at runtime. That is coherent but means the skill will run Node code in the agent runtime with filesystem and network access.

Credentials

Code reads/uses environment variables not declared in the skill metadata: MCP_URL and MCP_API_KEY (mcp-client.js) and standard proxy env vars (HTTPS_PROXY/HTTP_PROXY) plus system proxy detection. MCP_API_KEY is a sensitive credential; the skill does not declare it as required or primary. The default MCP_API_KEY falls back to a public key string, but the ability to override via env means sensitive secrets could be provided — the skill does not document or request them explicitly in metadata.

Persistence & Privilege

The skill does not request always:true and does not alter other skills' configs. It writes cache files under scripts/cache and includes a warm-up script (init.js) that can create persistent cache artifacts and perform heavy querying. Writing cache to disk is expected for a data-layer but is persistent and can grow; this is legitimate but worth noting.

What to consider before installing

This skill appears to implement the claimed Polymarket/PredicTradar data layer, but several implementation details are inconsistent with the declared metadata and introduce risk: - The code expects/reads environment variables (MCP_URL, MCP_API_KEY) and proxy env vars even though the registry metadata lists no required env. If you set MCP_API_KEY, treat it as a secret and only provide it in a controlled environment. - The skill runs local commands to detect proxies (scutil, python3 via execFileSync). If you run this on a machine where those binaries exist, they will be executed. Consider running in an isolated container if you are concerned. - The gamma-client disables TLS certificate verification (rejectUnauthorized: false) when establishing TLS connections; this weakens transport security and can expose you to man-in-the-middle tampering of gamma-api.polymarket.com interactions. - The skill writes cache files under scripts/cache and includes a warm-up script that performs many queries; expect disk usage and potentially heavy network/API usage. Review and control when/if init.js is run. - The absence of declared env requirements is an inconsistency — ask the publisher (or inspect code) before supplying any credentials or exposing sensitive networks. If you decide to install, run it in a sandboxed environment, avoid supplying sensitive credentials unless necessary, and consider patching the TLS setting (enable certificate verification) and removing or restricting local exec calls if you cannot trust the runtime.

Polymarket Data Access Layer

This skill is the shared data layer for the repository. It exists so that individual skills do not need to re-implement MCP session handling, query helpers, market metadata lookups, or local caching logic.

---

Data Source Priority

1. PredicTradar MCP Server  https://api.predictradar.ai/api/mcp/v2  (primary)
2. polymarket-cli           polymarket <command>                    (service degradation fallback)
3. Polymarket Data API      https://data-api.polymarket.com         (final fallback)

Use the PredicTradar MCP Server by default. It is the canonical shared entry point for this repo.

---

Current MCP Notes

The live MCP service now requires a full MCP session handshake:

1. Call initialize
2. Read the mcp-session-id response header
3. Send notifications/initialized
4. Reuse the session header for tools/list and tools/call

The repository wrapper at mcp-client.js already handles this automatically, so skills should call the wrapper instead of implementing raw MCP requests unless they need low-level debugging.

Health endpoint observed on March 31, 2026:

• service: predictradar-mcp
• version: 1.0.0
• protocolVersion: 2025-03-26

---

MCP Capabilities

The current live tool catalog includes:

Tool	Purpose	Notes
get_traders	Trader list with sorting and pagination	Sort fields include volume_24h, volume_7d, volume_30d, pnl_24h, pnl_7d, pnl_30d, win_rate
get_trader_detail	Detailed trader profile	Includes positions, recent activity, and analysis payloads
get_markets	Market list	Supports status, search, limit, offset
get_market_detail	Single-market detail	Newer high-level tool, useful when a skill already has a conditionId
get_leaderboard	Ranked trader leaderboard	period: 24h, 7d, 30d, all
get_market_stats	Aggregate market statistics	Includes volume, trader counts, active markets, hot markets
search_events	Event search	Supports query, category, status, limit
run_query_preview	Preferred read-only SQL preview	Preview mode only, limited rows
run_query	Legacy alias for preview SQL	Keep compatibility, but prefer run_query_preview in new docs
open_query_stream	Streamed SQL export	Use for larger result sets instead of overloading preview queries
list_tables	Table catalog	Supports category filter: trading, market, user, system, all
describe_table	Table schema inspection	Can include sample rows

Key documentation updates compared with the older version:

• The handshake requirement must be documented explicitly.
• get_market_detail should be listed as a first-class tool.
• run_query_preview should be treated as the preferred preview-query tool.
• run_query should be described as a compatibility alias.
• open_query_stream should be documented for larger exports.

---

Current Table Inventory

Live list_tables currently returns two trading tables:

Table	Description	Approx. Rows
trades	Historical trade records including trade, mint, burn, and redeem actions	~296.6M
positions	Current and historical positions	~30.5M

These row counts are service-side approximations and may grow over time.

---

Key Schema Notes

trades

Important columns currently exposed by describe_table("trades"):

• id
• created_at
• updated_at
• platform
• wallet_address
• platform_id
• tx_hash
• transaction_hash
• condition_id
• trader_id
• market_id
• token_id
• side
• type
• outcome
• outcome_side
• price
• size
• amount
• fee
• fee_amount
• outcome_index
• profit
• usd_amount
• chain_id
• block_number
• block_timestamp
• traded_at

Practical takeaways:

• amount remains the most portable trade-size field for aggregate SQL.
• usd_amount is available and nullable, which is useful for whale-style filters.
• type is not just trade; it also includes mint, burn, and redeem.
• condition_id and market_id are both available directly in the table, so legacy mapping tables should not be required for normal skill flows.

positions

Important columns currently exposed by describe_table("positions"):

• id
• created_at
• updated_at
• platform
• wallet_address
• trader_id
• market_id
• token_id
• condition_id
• outcome
• outcome_index
• outcome_side
• size
• size_frozen
• avg_price
• avg_entry_price
• current_price
• initial_value
• current_value
• total_bought
• realized_pnl
• unrealized_pnl
• unrealized_pnl_percent
• daily_pnl_change
• is_redeemable
• is_closed
• chain_id
• last_updated_at
• opened_at
• closed_at

Practical takeaways:

• avg_entry_price, current_price, is_redeemable, and lifecycle timestamps should now be reflected in any field documentation.
• positions is richer than the older docs implied, so skills can describe both PnL state and lifecycle state more precisely.

---

Quick Start

const mcp = require("../../polymarket-data-layer/scripts/mcp-client");

// health + handshake
const ok = await mcp.ping();
const health = await mcp.health();
const init = await mcp.initialize();

// high-level tools
const leaderboard = await mcp.getLeaderboard({ period: "7d", rankBy: "pnl", limit: 10 });
const traders = await mcp.getTraders({ sortBy: "pnl_7d", order: "desc", limit: 20 });
const markets = await mcp.getMarkets({ status: "active", search: "Fed", limit: 20 });
const market = await mcp.getMarketDetail("0x...");

// preview query
const rows = await mcp.query(`
  SELECT condition_id, SUM(amount) AS volume_24h
  FROM trades
  WHERE traded_at >= now() - INTERVAL 1 DAY
    AND type = 'trade'
  GROUP BY condition_id
  ORDER BY volume_24h DESC
  LIMIT 20
`);

// streamed query export
const stream = await mcp.openQueryStream(`
  SELECT wallet_address, SUM(amount) AS volume_30d
  FROM trades
  WHERE traded_at >= now() - INTERVAL 30 DAY
  GROUP BY wallet_address
`);

---

Environment Variables

MCP_URL=https://api.predictradar.ai
MCP_API_KEY=pr_public_predictradar

The wrapper already defaults to these values unless overridden.

---

Shared Scripts

mcp-client.js

Use this for:

• session-aware MCP calls
• preview SQL queries
• streamed query exports
• health and initialization checks
• high-level market and trader tools

Highlights:

• automatic MCP session handshake
• retry support for transient network issues
• openQueryStream, consumeQueryStream, cancelQueryStream, and queryStream
• wrappers for getTraders, getTraderDetail, getLeaderboard, getMarketStats, getMarkets, getMarketDetail, and searchEvents

mcp-examples.js

Run this when you need to inspect:

• health and handshake behavior
• current tool inventory
• table catalog and schema previews
• example preview queries
• stream-export behavior
• trader lookup examples

gamma-client.js

Use this when a skill needs:

• market metadata by conditionId
• market-to-domain mapping
• keyword-based market discovery
• event URL resolution

queries.js

Use this for reusable repo-level aggregations such as:

• all addresses
• base trading metrics
• ROI metrics
• address-to-domain volume breakdowns

smartmoney.js

Use this only when a skill explicitly needs the local smart-money classification layer. Prefer read-only cache access when possible unless the workflow truly requires a fresh classification.

cache.js

Use this for local file-backed cache reads and writes inside longer-running scripts.

---

Query Guidance

Preview Queries

Use preview SQL when:

• you need a compact result set
• the skill only needs top rows or aggregate rows
• a result set comfortably fits within preview limits

Guidance:

• use mcp.query(...) or mcp.queryWithRetry(...)
• keep result sizes tight with LIMIT
• explicitly filter type = 'trade' when you do not want mint, burn, or redeem

Streamed Exports

Use open_query_stream when:

• you need more rows than a preview call should return
• a skill needs a larger export for downstream processing
• you want a preview plus a temporary stream URL

Fallbacks

If MCP is unavailable:

1. fall back to polymarket-cli when appropriate
2. fall back to the Polymarket Data API as a final option

---

Cache Policy

Recommended cache behavior:

• prefer cached metadata when freshness is not critical
• bypass cache when the user explicitly asks for the latest or real-time data
• treat smart-money classification as a separate cacheable enrichment layer
• avoid over-caching rapidly changing short-window trading snapshots

---

Important Notes

1. condition_id is the canonical cross-system market key.
2. wallet_address should be normalized to lowercase for SQL comparisons.
3. run_query is no longer the best term for new docs; describe it as a legacy alias and prefer run_query_preview.
4. open_query_stream should be mentioned anywhere a skill may need larger result sets.
5. Skills should not document raw MCP session handling unless they are intentionally teaching low-level protocol behavior; ordinary skills should point to mcp-client.js.