superior-trade/superior-skills/polymarket

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` 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.

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 the required capability or collateral is unavailable, 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 /runtime/executions and report the real API result. Never fabricate fills, order IDs, balances, or status.

Supported action:

{
  "venue": "polymarket",
  "account_address": "0x1234567890123456789012345678901234567890",
  "action": {
    "type": "placeMarketOrder",
    "tokenID": "1234567890",
    "side": "BUY",
    "amount": "10",
    "price": 0.55,
    "orderType": "FOK"
  }
}

Fast confirmation format:

Order Summary:
• Venue: Polymarket
• Wallet address: [wallet address from GET /wallet] — capability: [Polymarket support from GET /context/venues]
• 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)

Inspect the durable execution with GET /runtime/executions/{id}. If the Unified contract does not expose the current position or open-order read the user needs, say that it is unavailable instead of querying with undisclosed venue credentials.

Safety

Security & Permissions

This skill requires exactly one credential: a Superior Trade API key. The only secret the agent uses is SUPERIOR_TRADE_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 a venue withdrawal or portfolio exit unless the exact operation is present in Unified OpenAPI
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).

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, first check Unified OpenAPI for a supported live position/order read. If none exists, say exposure verification is unavailable; do not infer it from deployment status or proceed with an exit, replacement, restart, or exposure-based sizing decision whose safety depends on that state.
• 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