/polymarket

name: polymarket
description: "Use when the user wants to trade, research, or backtest Polymarket prediction markets through Superior Trade — finding markets by slug or event URL, placing a single immediate market order, writing NautilusTrader strategies, running filled-data backtests, funding pUSD, or deploying and monitoring a live Polymarket strategy."
metadata:
  version: 2.0.0
  updated: 2026-08-12
  homepage: https://superior.trade
  source: https://github.com/Superior-Trade
  primaryEnv: SUPERIOR_TRADE_API_KEY
  auth:
    type: api_key
    env: SUPERIOR_TRADE_API_KEY
    header: "x-api-key"
    scope: "Use the authenticated user's Unified API account, managed wallet, market context, backtests, deployments, and supported typed Polymarket executions. Cannot export private keys or access other users' data."
  env:
    - name: SUPERIOR_TRADE_API_KEY
      description: "Superior Trade API key for Unified API account, wallet, context, backtest, deployment, and typed execution requests."
      required: true
      type: api_key
  externalEndpoints:
    - url: https://api.superior.trade
      purpose: "Unified account, wallet, market context, typed executions, filled-data backtests, deployments, and logs"

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.

Read [`../../references/unified-runtime.md`](../../references/unified-runtime.md) before any Superior Trade request. Use only methods, fields, and capabilities published by Unified OpenAPI.

**Base URL:** `https://api.superior.trade`. If the environment configures a different base URL, use that instead. **Auth:** Prefer `x-api-key: <api_key>` for Superior Trade product API keys. Browser/session callers may use `Authorization: Bearer <token>`. **Docs:** `GET /openapi.json` (Unified OpenAPI contract)

Reference files

Load these on demand — each is the full detail behind a summary below.

| Read | When | | --- | --- | | `references/api.md` | You need Unified route selection for account, wallet, market discovery, typed execution, backtest, or deployment. | | `references/strategy-authoring.md` | You are writing NautilusTrader strategy code — structure, order submission, dollars-to-shares conversion, multi-instrument setups, available data. | | `references/example-strategies.md` | You want a worked starting point: carry/yield harvesting, momentum/news fade, or spread capture. | | `references/strategies.md` | You are choosing an archetype for the user's thesis and need the fit/anti-fit table. | | `references/troubleshooting.md` | A strategy source, backtest, or deployment is failing, or a deployment trades zero times. |

Gotchas

Environment-specific facts that defy reasonable assumptions. Read these before acting.

• **Wallet reads are not bootstrap or funding mutations.** Use `GET /wallet` only for the managed wallet data it returns. If a required Polymarket funding action is absent from the Unified contract, report it as unavailable.
• **Backtests are built from filled `TradeTick` data, not a full order book.** They cannot model queue position or liquidity, so a strategy that depends on resting-order fills will look better in backtest than it trades. Say this when presenting results.
• **An exact market slug is required before writing a strategy.** Get it from `GET /context/markets`; if the user pastes a Polymarket event URL, pass the whole URL as the query so child markets expand.
• **Prices are probabilities between 0 and 1.** Sizing is in shares, not dollars — convert with `shares = dollars / price` (see `references/strategy-authoring.md`).
• **Credential storage is contract-defined.** Use only the form published for `PUT /runtime/deployments/{id}/credentials`; never infer or send undisclosed key material.

Setup

API Key

This skill uses the same Superior Trade API key as every other venue — there is no separate prediction-market key:

x-api-key: $SUPERIOR_TRADE_API_KEY

If `SUPERIOR_TRADE_API_KEY` is not set, use the registration and verification flow in the `superior-trade-auth` skill.

Wallet and Funding

The managed wallet is read through `/wallet`. Polymarket support is discovered through `/context/venues`; exact capabilities come from `/openapi.json`.

Before live trading:

1. Read the managed wallet with `GET /wallet`. 2. Check Polymarket and Nautilus support with `GET /context/venues` and `GET /runtime/frameworks`. 3. Confirm the wallet has the required balance and readiness exposed by Unified API. 4. If a required onboarding or pUSD funding action is absent from `GET /openapi.json`, stop and report it. 5. Create a Unified deployment with strategy code and config. 6. Store credentials with `PUT /runtime/deployments/{id}/credentials` only when the current contract requires it. 7. Start the deployment only after the user explicitly confirms.

Use only the credential schema published by Unified API. Never infer a secret or wallet field from an older payload.

Account Endpoints

Current account/funding endpoints:

• `GET /account`
• `GET /wallet`
• `GET /wallet/deposits`
• `GET /wallet/withdrawals`
• `POST /wallet/withdraw`
• `GET /context/venues`
• `POST /runtime/executions`

Single Immediate Market Orders

Use `POST /runtime/executions` 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_API_KEY`. 2. Fetch `GET /wallet`. 3. If selecting a non-default managed account, set top-level `account_address` only to an address verified by `GET /wallet`. 4. Check `GET /context/venues` and the wallet balance. If t