# Polymarket

> Discover Polymarket markets, place single immediate market orders, run v3 filled-data backtests, and plan/start live Nautilus deployments through Superior Trade's managed cloud.

- **Type:** Skill
- **Install:** `agentstack add skill-superior-trade-superior-skills-polymarket`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Superior-Trade](https://agentstack.voostack.com/s/superior-trade)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Superior-Trade](https://github.com/Superior-Trade)
- **Source:** https://github.com/Superior-Trade/superior-skills/tree/main/skills/polymarket

## Install

```sh
agentstack add skill-superior-trade-superior-skills-polymarket
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Polymarket Prediction Market Trading

Trade prediction markets on Polymarket through Superior Trade. Discover markets, place single immediate market orders, write NautilusTrader strategies, backtest against historical trade data, and deploy live — all through one API.

**Base URL:** Use the environment-configured Superior Trade API base URL. Production is `https://api.superior.trade/v3`; UAT may use `https://api-uat.superior.trade/v3`.
**Auth:** Prefer `x-api-key: ` for Superior Trade product API keys. Browser/session callers may use `Authorization: Bearer `.
**Docs:** `GET /v3/docs` (interactive reference), `GET /v3/openapi.json` (OpenAPI spec)

## Setup

### API Key

This skill uses an existing Superior Trade API key:

```
x-api-key: $SUPERIOR_TRADE_PM_API_KEY
```

If `SUPERIOR_TRADE_PM_API_KEY` is not set, ask the user to provide or configure their Superior Trade API key through their normal credential flow. Do **not** call `POST /v3/account/onboard`; that path is not part of the current main API.

### Wallet and Funding

Trading-account wallets are managed through `/v3/account`. Polymarket readiness and balances are checked through `/v3/account/{address}/status/polymarket`. Deposits are not "send-to-address instructions"; the v3 API wraps Polygon USDC/USDC.e from an owned Superior wallet into Polymarket pUSD through `/v3/portfolio/polymarket/deposit`.

Before live trading:

1. List or create a trading account with `/v3/account`.
2. Bootstrap Polymarket setup for the wallet with `POST /v3/account/{address}/polymarket`.
3. Check readiness with `GET /v3/account/{address}/status/polymarket`; it reports onboarding, approvals, credentials, and balances.
4. If needed, deposit Polygon USDC/USDC.e with `POST /v3/portfolio/polymarket/deposit`.
5. Create a v3 deployment plan with strategy code and config.
6. Store credential metadata with `POST /v3/deployment/{id}/credentials` using only the owned `wallet_address`.
7. Start the deployment only after the user explicitly confirms.

The v3 credentials endpoint accepts wallet-address metadata only:

```json
{ "wallet_address": "0x1234567890123456789012345678901234567890" }
```

It rejects `private_key` and rejects wallet addresses outside the authenticated account list.

### Account Endpoints

Current account/funding endpoints:

- `GET /v3/account`
- `POST /v3/account`
- `PATCH /v3/account/{address}`
- `POST /v3/account/{address}/polymarket`
- `GET /v3/account/{address}/status/polymarket`
- `GET /v3/account/{address}/deposit-link`
- `POST /v3/portfolio/polymarket/deposit`
- `POST /v3/portfolio/polymarket/exit`
- `POST /v3/authorize-and-send/polymarket`

### Single Immediate Market Orders

Use `POST /v3/authorize-and-send/polymarket` when the user asks to place one immediate Polymarket bet/order. This is a fast path for a whitelisted `placeMarketOrder` action, not a strategy deployment. Do not create a deployment plan or run a backtest for a one-off order unless the user asks for a strategy or bot.

Required sequence:

1. Confirm auth with `SUPERIOR_TRADE_PM_API_KEY`.
2. Fetch `GET /v3/account`.
3. Set `action.from` only to a `wallet_address` returned in `items[]`. Never trust or invent an arbitrary `from` address; if the user supplied one, verify it appears in the account list before using it.
4. Check `GET /v3/account/{address}/status/polymarket` for that wallet. If onboarding, approvals, credentials, or available pUSD balance are not ready for the requested order, stop and report the blocker.
5. If the user already provided the complete order payload and explicit affirmative confirmation for that exact payload in the current conversation, submit it without asking unrelated follow-up questions. If not, show the exact payload and ask for confirmation before submitting.
6. Send exactly one request to `POST /v3/authorize-and-send/polymarket` and report the real API result. Never fabricate fills, order IDs, balances, or status.

Supported action:

```json
{
  "action": {
    "type": "placeMarketOrder",
    "from": "0x1234567890123456789012345678901234567890",
    "tokenID": "1234567890",
    "side": "BUY",
    "amount": "10",
    "price": 0.55,
    "orderType": "FOK"
  }
}
```

Fast confirmation format:

```
Order Summary:
• Venue: Polymarket
• Wallet address: [wallet_address from GET /v3/account] — readiness: [ready/blockers from status endpoint]
• Token ID: [tokenID]
• Side: [BUY/SELL]
• Amount: [amount] pUSD
• Limit price: [price]
• Order type: [orderType]

This will submit one REAL Polymarket market order immediately. Proceed? (yes/no)
```

Current Polymarket state checks:

- `GET https://data-api.polymarket.com/positions` — public current positions by wallet address
- `GET https://clob.polymarket.com/data/orders` — authenticated open orders through Polymarket CLOB credentials/client
- `GET https://clob.polymarket.com/data/order/{orderId}` — authenticated single-order lookup
- `GET https://clob.polymarket.com/data/trades` — authenticated fills/trade history

Do not advertise old/stale paths: `/v3/account/onboard`, `/v3/account/wallets`, `/v3/account/deposit/polymarket`, `/v3/account/withdraw/polymarket`, or `/v3/deployment/{id}/exit`.

## Safety

### Security & Permissions

This skill requires exactly **one credential**: a Superior Trade API key. The only secret the agent uses is `SUPERIOR_TRADE_PM_API_KEY`.

**Security rules (non-negotiable):**

1. **NEVER** ask users for private keys, seed phrases, or wallet credentials
2. **NEVER** log, store, or display private keys or seed phrases
3. **NEVER** fabricate wallet balances, API responses, market prices, or trade results
4. **NEVER** start a live deployment without explicit user confirmation
5. **NEVER** promise withdrawals — v3 supports Polymarket deposit and portfolio exit, not withdrawal to an external address
6. **Prefer user-friendly language** over internal technical names when speaking conversationally. Say "strategy" or "the bot" instead of internal class names or infrastructure details. If the user asks about the underlying technology, answer honestly (the platform uses NautilusTrader for strategy execution against Polymarket's CLOB).

| Can do                                                                               | Cannot do                            |
| ------------------------------------------------------------------------------------ | ------------------------------------ |
| List/create/rename trading accounts                                                   | Access other users' data             |
| Bootstrap Polymarket setup, check readiness, and deposit Polygon USDC/USDC.e to pUSD   | Export, accept, or view private keys |
| Search markets and run filled-data backtests                                          | Withdraw to an external address      |
| Read current Polymarket positions and open orders                                      | Guess holdings from deployment state |
| Plan deployments, store wallet-address credential metadata, start/stop/delete v3 runs  | Invent balances or trade results     |
| Close all Polymarket positions/orders with `/v3/portfolio/polymarket/exit` after confirmation | Transfer or bridge arbitrary funds   |

### Polymarket-Specific Risks (tell the user when relevant)

- **Prices are probabilities** — every outcome trades between 0.001 and 0.999 pUSD. A "cheap" 0.03 outcome is not a bargain; it is a ~3% market-implied probability.
- **Resolution risk** — positions held to resolution settle at exactly 0 or 1. A strategy can be up and still settle at zero if the outcome resolves against it.
- **Liquidity risk** — many markets have thin order books. Market orders can fill far from the displayed price. Prefer markets with meaningful `volume_24h` and `liquidity`.
- **Market end dates** — markets stop trading at `end_date`. Never deploy a strategy on a market that resolves before the strategy has time to work.
- **Rate limits** — Polymarket enforces ~30 order submissions/minute and ~100 data requests/minute per user. Strategies that cancel/replace on every tick can hit these fast.

### Live Deployment Confirmation

Before any **live deployment start**, the agent MUST present this summary and wait for an explicit affirmative response:

```
Deployment Summary:
• Deployment: [deployment_id]
• Venue: Polymarket
• Market(s): [market question(s)]
• Wallet address: [0x...] — readiness: [ready/blockers from status endpoint]
• Trade size/risk settings: [from deployment.config]
• Backtest reviewed: [backtest_id / result summary]

⚠️ This will trade with REAL funds. Proceed? (yes/no)
```

Do NOT start a live deployment without an explicit affirmative response.

## Agent Operating Rules

- **Verification-first:** Every factual claim about balance, market price, position, or deployment status MUST be backed by an API call in the current turn. NEVER assume → report → verify later.
- **Anti-hallucination:** If you can't call the API, say "I haven't checked yet." Every number must come from a real response.
- **Position/order state:** When the user asks what they hold, whether orders are open, whether a bot traded, or whether it is safe to stop/exit, fetch live Polymarket positions/orders first. Deployment status does not prove a position exists.
- **Backtest before deploy:** Always run a backtest and review results with the user before the first live deployment of any strategy.
- **Conversational:** Make API calls directly and present results conversationally. Show raw payloads only on request.
- **Proactive:** Ask for missing info conversationally, one concern at a time.

### Repeated Failures

If the same task fails 3+ times (e.g. strategy source/config keeps failing, backtest keeps erroring), stop and:

1. Summarize what was tried and what failed
2. Suggest a simpler approach or different parameters
3. If the issue appears to be model capability (complex multi-instrument logic), suggest switching to a more capable model for strategy generation

## Workflow

```
1. Confirm auth      →  Use existing `SUPERIOR_TRADE_PM_API_KEY`
2. Account setup     →  GET/POST /v3/account, then POST /v3/account/{address}/polymarket
3. Check readiness   →  GET /v3/account/{address}/status/polymarket; deposit if needed
4. Read live state   →  For holdings/order questions, fetch positions and open orders for the owned wallet
5. Deposit if needed →  POST /v3/portfolio/polymarket/deposit using Polygon USDC/USDC.e
6. Discover markets  →  POST /v3/markets/search — find candidate market slugs matching the user's interest; pass exact Polymarket event URLs directly when the user provides one
7. Write strategy    →  Author NautilusTrader Python strategy code from the closest archetype
8. Backtest          →  POST /v3/backtest with `strategyId`, `strategySource`, and `strategyConfig`
9. Review results    →  Poll/read backtest status/result/logs; analyze performance; iterate or proceed
10. Plan deployment  →  POST /v3/deployment with `{ deployment: { code, config } }`
11. Store credentials → POST /v3/deployment/{id}/credentials with an owned `wallet_address`
12. Start            →  Confirm with user → PATCH/PUT /v3/deployment/{id}/status `{ "action": "start" }`
13. Monitor/stop     →  Status/logs plus live positions/orders; stop with PATCH/PUT `/v3/deployment/{id}/status` `{ "action": "stop" }`
```

Deployment start requires both credential metadata and explicit user confirmation.

### Strategy Archetypes

When a user asks for a Polymarket strategy, pick an archetype first and then generate strategy code from it. This keeps backtest assumptions explicit and reduces silent drift.

- Probability Momentum (`probability-momentum` skill) — momentum, breakout, fast reaction in active markets
- Probability Mean Reversion (`probability-mean-reversion` skill) — overreaction fade and range-like behavior
- Deadline Drift (`deadline-drift` skill) — time-to-resolution behavior, especially before-date markets
- Related-Market Spread (`related-market-spread` skill) — relative-value checks across linked markets
- Large-Fill Pressure (`large-fill-pressure` skill) — repeated oversized fills with directional follow-through
- Catalyst Confirmation (`catalyst-confirmation` skill) — event thesis with market confirmation first

Operational rules:

1. Pick the closest archetype before coding.
2. Treat these as starting points, not validated strategies.
3. Generate a custom NautilusTrader strategy from the selected archetype and pass it directly to `POST /v3/backtest` via `strategySource` with matching `strategyConfig`.
4. Before any backtest request, confirm exact market slugs from search candidates.
5. Use filled-data assumptions (`TradeTick`) in backtests; do not promise queue/maker behavior without matching evidence.

Filled-data rule: Polymarket strategy logic should be driven by historical `TradeTick` replay in backtesting. If logic is quote-only, flag it as likely non-tradable in current backtest mode.

### Pre-Deployment Checklist (MANDATORY)

Before `PATCH /v3/deployment/{id}/status` or `PUT /v3/deployment/{id}/status` → `{"action":"start"}`:

1. **Backtest reviewed** — at least one completed backtest for this strategy code/config or materially similar logic, results shown to the user.
2. **Wallet readiness checked** — `GET /v3/account/{address}/status/polymarket` returns `onboarding.ready: true`. If not ready, resolve the blockers first; common blockers are no wallet, not onboarded, approvals missing, or balance below 5 USDC.
3. **Credentials metadata stored** — `POST /v3/deployment/{id}/credentials` with an owned `wallet_address`; do not send private keys.
4. **Market selected** — `POST /v3/markets/search` → confirm the exact `slug` to use. If the user gives a Polymarket event URL, pass that URL as the search query so child markets can be expanded. If search returns multiple plausible candidates, show the candidate questions/slugs and ask the user to choose. For backtests, require `backtestSupported: true`, `coverageStatus: "available"`, and a requested timerange inside the candidate `coverage`.
5. **Deployment config valid** — Polymarket live deployment config must include `instrument_id` formatted as `.POLYMARKET`.
6. **Current exposure checked when relevant** — if replacing, restarting, stopping, exiting, or sizing around existing exposure, fetch positions and open orders for the wallet first.
7. **User confirmation** — show the deployment summary and get an explicit "yes".

Do NOT skip any step or assume it passed without the API call.

## API Reference

### Account

#### GET `/v3/account` — List Trading Accounts

```json
{
  "items": [
    {
      "name": "Trading Account 1",
      "account_index": 1,
      "wallet_address": "0x1234567890123456789012345678901234567890"
    }
  ]
}
```

#### POST `/v3/account` — Create Trading Account

Creates a Privy server wallet-backed trading account. Limit: 3 active trading accounts per user.

```json
// Request
{ "name": "btc-carry" }

// Response
{
  "account": {
    "id": "acct_...",
    "label": "btc-carry",
    "account_index": 2,
    "wallet_address": "0x5678901234567890123456789012345678901234",
    "wallet_id": "privy-wallet-id",
    "status": "active"
  }
}
```

Error `409 trading_account_limit_reached` means the user already has 3 active trading accounts.

#### PATCH `/v3/account/{address}` — Rename Trading Account

```json
// Request
{ "name": "fed-spread" }

// Response
{
  "account": {
    "name": "fed-spread",
    "account_index": 2,
    "wallet_address": "0x5678901234567890123456789012345678901234"
  }
}
```

#### POST `/v3/account/{address}/polymarket` — Bootstrap Polymarket

Bootstraps Polymarket setup for an owned trading-account wallet. This returns onboarding steps and accepted assets; it does **not** return a deposit address.

```json
{
  "wallet_id": "privy-wallet-id",
  "chain": "polygon",
  "chain_id": 137,
  "account": {
    "type": "trading_account",
    "name": "fed-spread",
    "account_index": 2,
    "wallet_address": "0x56789012345678

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Superior-Trade](https://github.com/Superior-Trade)
- **Source:** [Superior-Trade/superior-skills](https://github.com/Superior-Trade/superior-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-superior-trade-superior-skills-polymarket
- Seller: https://agentstack.voostack.com/s/superior-trade
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.