Guide · Agent skill

How to use the Polymarket agent skill: install and examples

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The polymarket skill gives an AI agent reference material about Polymarket, a prediction market where people trade on the outcomes of events, plus working code for its real-time data client. This guide explains what the skill does, how to install it, how to ask for it, and how to subscribe to live Polymarket data in a TypeScript or JavaScript project. The skill does not place trades or fetch data by itself.

Polymarket Prediction Market Helper2025Emma/vibe-coding-cn · MIT Download the skill

Quick start

1Download and unzip. Download the skill ZIP from this page and unzip it so the skill folder contains SKILL.md and the references folder.
2Place the skill. Move the folder to ~/.claude/skills/ for all projects, or to .claude/skills/ in one project. Alternatively, upload the ZIP under Settings, Capabilities, Skills in the Claude apps.
3Set up Node.js and the client. Make sure Node.js and npm or yarn are installed, then run npm install @polymarket/real-time-data-client in your project.
4Ask for what you need. Describe the data you want, such as trades for one market or comments on one event, and ask for TypeScript or JavaScript code.
5Subscribe and test. Run the generated code with a single read-only subscription first, check the messages you receive, then add filters or authentication as needed.

What the polymarket skill makes the agent do

An agent skill is a folder of instructions and reference files that an AI agent can load when a task matches it. Once this skill is installed, the agent can answer questions about Polymarket's API and trading concepts and write code that uses the official real-time data client.

The client, @polymarket/real-time-data-client, subscribes to live activity such as completed trades and order matches, market comments, RFQ (Request for Quote) activity, crypto price feeds and market order book updates. The bundled documentation files describe how to use these services, but the skill itself does not place trades or fetch data.

How to install the polymarket skill

Download the ZIP of the skill from the page you are reading, then unzip it. Choose one of the following locations, depending on whether you want the skill for all your projects or just one.

Option A is a personal install that makes the skill available across your projects. Put the unzipped skill folder in ~/.claude/skills/. Option B is a project install that only applies to one codebase. Put the unzipped skill folder in your project's .claude/skills/ directory.

Option C is to upload the ZIP in the Claude apps. Open Settings, go to Capabilities, then choose Skills and upload the file.

Option A: ~/.claude/skills/ (all projects)
Option B: .claude/skills/ inside one project
Option C: Settings → Capabilities → Skills in the Claude apps

How to trigger the skill with natural requests

You do not need a special command. The skill's description covers Polymarket prediction markets, the API, trading, market data and real-time WebSocket streaming, so the agent should load it when your request matches those topics. Name Polymarket and the thing you want, and say whether you want code.

Requests that match the skill's stated use cases include the examples below. Be specific about the topic, market or event slug, and language, since the real-time client is TypeScript or JavaScript only.

Write a TypeScript script that streams live Polymarket trades for one market.
Which Polymarket WebSocket topic gives me order book updates?
Show me how to subscribe to comments on a Polymarket event.
Explain how Polymarket's order book (CLOB) settles trades.
Help me authenticate a clob_user subscription to see my own order updates.

Set up the real-time data client

Install the client package with npm in your project. The skill assumes Node.js (the source recommends version 14 or newer), with npm or yarn, and TypeScript is optional but recommended.

The basic pattern is to create a client with an onMessage handler and an onConnect handler. Subscriptions are sent from onConnect, and connect() opens the connection.

npm install @polymarket/real-time-data-client

import { RealTimeDataClient } from "@polymarket/real-time-data-client";

const onMessage = (message: Message): void => {
    console.log(message.topic, message.type, message.payload);
};

const onConnect = (client: RealTimeDataClient): void => {
    client.subscribe({
        subscriptions: [{
            topic: "activity",
            type: "trades"
        }]
    });
};

new RealTimeDataClient({ onMessage, onConnect }).connect();

Choose topics and filters for live data

Each topic has its own types. Activity covers trades and order matches, and can be filtered by event or market slug. Comments covers comment and reaction events, filtered by parent entity. RFQ needs no filters and no auth. Crypto prices can be filtered by symbol, such as BTC. CLOB market covers price changes, aggregated order books, last trade prices and market creation or resolution events.

Filters reduce the volume of messages your code has to process. The source notes that all timestamps are Unix timestamps and that market IDs are strings such as "100".

activity: trades, orders_matched; filters by event_slug or market_slug
comments: comment_created, comment_removed, reaction_created, reaction_removed
rfq: request and quote lifecycle events, no filters, no auth
crypto_prices and crypto_prices_chainlink: update, optional symbol filter
clob_user: order and trade for your own account, requires auth
clob_market: price_change, agg_orderbook, last_trade_price, market_created, market_resolved

client.subscribe({
    subscriptions: [{
        topic: "activity",
        type: "trades",
        filters: `{"market_slug":"btc-above-100k-2024"}`
    }]
});

Authenticate for private user data

The clob_user topic is the only one the source marks as requiring auth. It returns your own order updates and trade executions. Supply the API key, secret and passphrase from your Polymarket CLOB API credentials in the clob_auth field.

Keep these values out of source control. The example in the skill uses placeholder strings, which you should replace from environment variables or a secrets store rather than hard-coding them.

client.subscribe({
    subscriptions: [{
        topic: "clob_user",
        type: "*",
        clob_auth: {
            key: "your-api-key",
            secret: "your-api-secret",
            passphrase: "your-passphrase"
        }
    }]
});

Safety notes: scripts, network and trading

The skill runs no scripts. It does use the network, because the code you write opens WebSocket connections to Polymarket services. Review any generated code before running it, especially if it handles credentials.

The skill is not a trading system. It provides no risk controls, so trading code written from its documentation can lose funds if it has bugs. Test against small or read-only subscriptions before you connect anything that places orders. The skill's own best practices recommend reconnection logic for production, calling disconnect() when finished, handling authentication errors, and unsubscribing from unused streams.

Scripts: none bundled
Network: yes, for your WebSocket and API code
Credentials: needed only for clob_user, keep them secret
Trading: not provided; you must add your own controls

What people use it for

Building a dashboard that shows live trades for one Polymarket event
Monitoring comments and reactions on a market for moderation or research
Streaming crypto price feeds alongside prediction market activity
Learning how the Polymarket API and CLOB order book fit together

Frequently asked questions

How do I install the polymarket skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or into .claude/skills/ inside one project. You can also upload the ZIP in the Claude apps under Settings, Capabilities, Skills.

What do I need to use the polymarket skill?

You need Node.js (the source recommends 14 or newer), npm or yarn, and the npm package @polymarket/real-time-data-client. Private user data also needs a Polymarket CLOB API key, secret and passphrase.

Is the polymarket skill free?

The skill is published under the MIT licence, which is listed on this page. The page does not state pricing for Polymarket services, so check Polymarket's own terms for any costs of its platform.

Can the polymarket skill place trades for me?

No. The skill provides documentation and code examples for reading data and using the API, but it does not place trades or fetch data itself. Any trading code you write from it has no built-in risk controls.

Does the polymarket skill work with Python?

No. The source states that the real-time client is TypeScript and JavaScript only, so Python projects are not a good fit for this skill.

Why are some files like learn.md or llms-full.md missing?

SKILL.md names learn.md and llms-full.md, but the bundled file list for this skill does not include them. Work from the files that are present, such as api.md, trading.md and realtime-client.md.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you are a developer or data analyst building a dashboard, monitor or data feed in TypeScript or JavaScript that needs live Polymarket data. Pick something else if you want a ready-made betting or automated trading tool, or if your project is in Python, because this skill provides no trade execution or risk controls.

Download the skill