---
title: PolyTrackers Agent Skill
stable_url: https://polytrackers.com/skill.md
catalog_fingerprint: sha256-4125e55d1d69152f4a3796da33d37d90172e8282ed656f45a409978ce45a14d7
---

# PolyTrackers Agent Skill

Use this skill when an agent needs market intelligence, anomaly context, copy-trading review, mock experiments, API key help, or subscription/credit guidance for PolyTrackers.

Stable URL: `https://polytrackers.com/skill.md`

MCP catalog fingerprint: sha256-4125e55d1d69152f4a3796da33d37d90172e8282ed656f45a409978ce45a14d7

## Safety defaults

- Treat all PolyTrackers outputs as informational decision support, not financial advice.
- Prefer read-only calls first. Use write tools only when the user clearly asks for the action.
- Run preflight/dry-run before any write that supports it.
- Never place, cancel, or otherwise execute a real trade unless the user explicitly approves the exact action, market, side, size, price/slippage constraints, and account/wallet context.
- Do not claim guaranteed profit, risk-free trades, or investment outcomes.
- Do not expose API keys, secrets, passphrases, webhook secrets, or bearer tokens in logs or responses.

## MCP vs REST

Use MCP when:

- The client supports MCP tools/resources/prompts (Claude Desktop, Cursor, Codex, OpenClaw, or another MCP host).
- You want agent-friendly discovery through `pt_mcp_capabilities_get` or `polytrackers://mcp/capabilities`.
- You need composed workflows such as market intel, anomaly context, copy-trading digest, trade preflight, or mock experiment runs.
- You want tool annotations, tier/scope errors, truncation, and safe dry-run behavior handled consistently.

Use REST/OpenAPI when:

- You are building a deterministic integration, backend service, dashboard, or webhook receiver.
- Your client does not support MCP.
- You need direct endpoint control, custom pagination, or the machine-readable contract at `/api/openapi.json`.
- You are integrating public feeds or service-auth endpoints outside an interactive agent session.

Useful URLs:

- MCP endpoint: `https://polytrackers.com/api/mcp`
- MCP stdio bridge: `@polytrackers/mcp-stdio`
- API docs: `https://polytrackers.com/docs/api`
- OpenAPI JSON: `https://polytrackers.com/api/openapi.json`
- Agent skill: `https://polytrackers.com/skill.md`

## Agent API Key setup and scopes

Create an Agent API Key from PolyTrackers Profile. The same `ptk_...` bearer key works for MCP server access and direct REST/API requests when scopes allow. Pass it as:

```txt
Authorization: Bearer ptk_...
```

For MCP stdio clients, set:

```sh
POLYTRACKERS_API_KEY=ptk_...
POLYTRACKERS_MCP_URL=https://polytrackers.com/api/mcp # optional default
POLYTRACKERS_MCP_TIMEOUT_MS=60000                    # optional default
```

Scopes:

| Scope           | Use                                                                                              | Notes                                                                         |
| --------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| `signals:read`  | Market, anomaly, account, recommendations, mock analytics, and most read workflows               | Default Agent API Key scope.                                                  |
| `trade:execute` | Real Polymarket trade execution after preflight/readiness gates                                  | Pro may request this narrow trading scope; `agent:full` also satisfies it.    |
| `agent:scan`    | Trigger anomaly scans                                                                            | Pro may request this narrow automation scope; `agent:full` also satisfies it. |
| `agent:full`    | Full agent writes, mock writes, webhooks, alerts, and real-trade write access where tier permits | Elite keys may request this scope. Use dry-run/preflight first.               |

Key limits and expiry are enforced server-side. Keep at most two active Agent API Keys; rotate by generating a replacement, updating clients and agents, then revoking the old key. If a generated key is rejected by scope/tier checks, regenerate it with the required scope after confirming the account tier allows it.

## Pro vs Elite availability

- Pro with `signals:read`: read-only market/anomaly/copy intelligence and mock analytics. Pro may also request `trade:execute` for real trade execution and `agent:scan` for scan automation.
- Some non-trade write tools are Pro-tier but require `agent:full`; generated Pro keys should treat them as unavailable unless the capabilities payload shows that scope is present.
- Elite: `agent:full` access can use the broad write surface and remains a superset for real trade execution.
- The authoritative source is the MCP capabilities payload. At session start, call `pt_mcp_capabilities_get` and inspect `caller.tier`, `caller.scopes`, and each tool's `requiredTier`/`requiredScope` before planning actions.

Important tool groups:

- Market intelligence: `pt_market_intel_get`, `pt_markets_search`, `pt_markets_batch_get`, `pt_clob_price_get`.
- Anomalies: `pt_anomalies_list`, `pt_anomalies_get`, `pt_anomaly_context_get`, `pt_anomalies_batch_get`, `pt_anomalies_performance_get`, `pt_scan_trigger`.
- Copy trading: `pt_copy_trading_digest_get`, `pt_recommendations_get`, `pt_trader_profile_get`, `pt_trader_profile_batch_get`, `pt_trader_lookup`, `pt_leaderboard_get`.
- Mock experiments: `pt_mock_experiment_run`, `pt_mock_wallet_create`, `pt_mock_trade_place`, `pt_mock_resolve_run`, `pt_mock_reconcile_run`, analytics/export tools.
- Account/API: `pt_account_get`, `pt_account_stats_get`, `pt_account_risk_profile_get`, `pt_api_keys_list`, `pt_api_key_revoke`, `pt_mcp_capabilities_get`.
- Real trading: `pt_trade_preflight` first, then `pt_trade_execute` with `trade:execute` or `agent:full` only after explicit user approval. `pt_trade_order_cancel` remains Elite-only.

## Common workflows

### Market intel

1. Call `pt_mcp_capabilities_get` once.
2. Use `pt_market_intel_get` for a composed summary, or `pt_markets_search` + `pt_clob_price_get` for direct inspection.
3. Present uncertainty, data freshness, and relevant market identifiers. Do not recommend a trade as guaranteed or risk-free.

### Anomaly scan

1. Use `pt_anomalies_list` or `pt_anomaly_context_get` for existing signals.
2. If the user asks to refresh and the key has `agent:scan`, call `pt_scan_trigger`.
3. Respect 429 responses and `Retry-After`; do not loop scan requests.

### Copy-trading review

1. Use `pt_copy_trading_digest_get` or combine `pt_recommendations_get`, `pt_trader_profile_get`, `pt_whale_activity_get`, and `pt_whale_performance_get`.
2. Explain why a wallet/trader appears relevant, including risk profile and known gaps.
3. Ask for explicit confirmation before any trade-related next step.

### Mock experiment

1. Prefer `pt_mock_experiment_run` for composed simulation.
2. For manual flows, create/list a mock wallet, place a mock trade with dry-run first, then resolve/reconcile as requested.
3. Label results as simulation only; do not imply live execution.

### API credit/subscription questions

1. Read `pt_account_get`, `pt_account_stats_get`, and `polytrackers://account/tier` when available.
2. Use `pt_mcp_capabilities_get` to explain which tools are blocked by tier or scope.
3. For billing or upgrade guidance, point to PolyTrackers account/subscription UI rather than inventing prices or credits.

## Client examples

### Claude Desktop

```jsonc
{
  "mcpServers": {
    "polytrackers": {
      "command": "npx",
      "args": ["-y", "@polytrackers/mcp-stdio"],
      "env": {
        "POLYTRACKERS_API_KEY": "ptk_...",
      },
    },
  },
}
```

### Cursor

Add the same server block to Cursor's MCP configuration:

```jsonc
{
  "mcpServers": {
    "polytrackers": {
      "command": "npx",
      "args": ["-y", "@polytrackers/mcp-stdio"],
      "env": {
        "POLYTRACKERS_API_KEY": "ptk_...",
        "POLYTRACKERS_MCP_URL": "https://polytrackers.com/api/mcp",
      },
    },
  },
}
```

### Codex

Configure the stdio bridge as an MCP server for Codex, with the key supplied from your local secret store/environment:

```jsonc
{
  "mcpServers": {
    "polytrackers": {
      "command": "npx",
      "args": ["-y", "@polytrackers/mcp-stdio"],
      "env": {
        "POLYTRACKERS_API_KEY": "${POLYTRACKERS_API_KEY}",
      },
    },
  },
}
```

### OpenClaw

Register an MCP server named `polytrackers` that runs the stdio bridge and reads `POLYTRACKERS_API_KEY` from the environment or secret manager:

```jsonc
{
  "mcpServers": {
    "polytrackers": {
      "command": "npx",
      "args": ["-y", "@polytrackers/mcp-stdio"],
      "env": {
        "POLYTRACKERS_API_KEY": "${POLYTRACKERS_API_KEY}",
        "POLYTRACKERS_MCP_TIMEOUT_MS": "60000",
      },
    },
  },
}
```

## Troubleshooting

- `AUTH_MISSING` or 401: confirm the `Authorization` header or `POLYTRACKERS_API_KEY` is present and has no extra quotes/spaces.
- `api_key_invalid` / `api_key_expired`: revoke and regenerate the key; update every local MCP client config.
- `TIER_UPGRADE_REQUIRED`: the account tier does not meet the tool/endpoint requirement.
- `SCOPE_REQUIRED`: regenerate the key with the required scope if the tier allows it.
- `RATE_LIMITED` / 429: obey `Retry-After`; back off instead of retrying in a tight loop.
- Empty or truncated results: lower `limit`, narrow filters, or use batch/detail tools for follow-up.
- Stdio bridge issues: verify `npx -y @polytrackers/mcp-stdio` can run, the key is in env, and logs are read from stderr (stdout is reserved for JSON-RPC frames).

## Maintainer sync guardrail

When MCP tool names, tiers, scopes, REST auth semantics, rate limits, API key generation behavior, or trading safety behavior change, update this file in the same PR. Then update the MCP catalog fingerprint above. The unit test `app/api/mcp/catalog-skill-sync.test.ts` fails when the catalog fingerprint no longer matches.