# Activity
Source: https://polymarket-data.com/data/activity
Retrieve a chronological feed of trades, rewards, splits, merges, and conversions.
`client.data.core.getActivity` delivers a time-ordered view of wallet events. It’s perfect for
portfolio dashboards, notification feeds, and audit tooling.
## Request
```ts theme={null}
const feed = await client.data.core.getActivity(params);
```
### Parameters
\| Name | Type | Required | Default | Notes |
\| --------------- | ----------------------- | -------- | ------- | ---------------------------------------------------------------------- | ------------------ | --------------- |
\| `user` | `string` (address) | ✅ | – | Wallet or proxy address. |
\| `limit` | `number` (0–500) | | `100` | Page size. |
\| `offset` | `number` (0–10000) | | `0` | Page offset. |
\| `market` | `string[]` | | – | Condition IDs (mutually exclusive with `eventId`). |
\| `eventId` | `number[]` | | – | Event IDs (mutually exclusive with `market`). |
\| `type` | array of activity enums | | – | Filter by `TRADE`, `REDEEM`, `MERGE`, `SPLIT`, `REWARD`, `CONVERSION`. |
\| `start` | `number` (≥ 0) | | – | Unix timestamp lower bound. |
\| `end` | `number` (≥ 0) | | – | Unix timestamp upper bound. |
\| `sortBy` | `"TIMESTAMP" | "TOKENS" | "CASH"` | | `"TIMESTAMP"` | Sorting metric. |
\| `sortDirection` | `"ASC" | "DESC"` | | `"DESC"` | Sorting order. |
\| `side` | `"BUY" | "SELL"` | | – | Trade side filter. |
## Response
```ts theme={null}
type Activity = {
proxyWallet: string;
timestamp: number;
conditionId: string;
type: "TRADE" | "SPLIT" | "MERGE" | "REDEEM" | "REWARD" | "CONVERSION";
size: number;
usdcSize: number;
transactionHash: string;
price: number;
asset: string;
side?: "BUY" | "SELL";
outcomeIndex: number;
title: string;
slug: string;
icon: string;
eventSlug: string;
outcome: string;
name: string;
pseudonym: string;
bio: string;
profileImage: string;
profileImageOptimized: string;
};
```
## Usage example
```ts theme={null}
const feed = await client.data.core.getActivity({
user: "0x56687bf447db6ffa42ffe2204a05edaa20f55839",
type: ["TRADE", "REDEEM"],
limit: 25,
});
feed.forEach((entry) => {
console.log(`${entry.type} at ${new Date(entry.timestamp * 1000).toISOString()}`);
});
```
## Failure modes
* Missing `user` → validation error.
* Conflicting filters → validation error referencing both fields.
# Holders
Source: https://polymarket-data.com/data/holders
Retrieve top holders for specific market outcome tokens.
`client.data.core.getHolders` reveals which wallets hold outcome tokens for the supplied markets.
Great for leaderboards and liquidity dashboards.
## Request
```ts theme={null}
const breakdown = await client.data.core.getHolders(params);
```
### Parameters
| Name | Type | Required | Default | Notes |
| ------------ | ------------------- | -------- | ------- | ---------------------------- |
| `market` | `string[]` | ✅ | – | Condition IDs (0x + 64 hex). |
| `limit` | `number` (0–500) | | `100` | Holders per outcome token. |
| `minBalance` | `number` (0–999999) | | `1` | Minimum balance filter. |
## Response
```ts theme={null}
type HolderData = {
token: string;
holders: Array<{
proxyWallet: string;
bio: string;
asset: string;
pseudonym: string;
amount: number;
displayUsernamePublic: boolean;
outcomeIndex: number;
name: string;
profileImage: string;
profileImageOptimized: string;
}>;
};
```
## Usage example
```ts theme={null}
const breakdown = await client.data.core.getHolders({
market: ["0x49252732f0bfe99f2ab09366230607eb9562fa6a56557a10ddcd7dd2198cf588"],
limit: 10,
});
breakdown.forEach((entry) => {
console.log(`Token ${entry.token} has ${entry.holders.length} visible holders`);
});
```
## Failure modes
* Missing `market` → validation error.
* `limit` > 500 or malformed condition IDs → validation error.
# Overview
Source: https://polymarket-data.com/data/index
Explore positions, trades, activity, holders, and other classic Polymarket data endpoints.
The `client.data` namespace mirrors Polymarket’s classic data service. It is split into two
segments:
* **Core** — portfolio-focused endpoints (`client.data.core.*`).
* **Misc** — supporting analytics (`client.data.misc.*`).
**Guaranteed shape:** Every request and response is validated with Zod before data reaches your
application. Schema mismatches surface immediately with descriptive errors.
Token balances, cash/percent PnL, redeemable/mergeable flags.
Historical fills with filters for user, market IDs, and trade side.
Chronological feed of trades, rewards, splits, merges, and conversions.
Outcome-level holder breakdowns with profile metadata.
Aggregate USDC exposure per wallet, with optional market filtering.
Token-level open interest snapshots and global aggregates.
Real-time volume for individual events, including per-market totals.
Count how many markets a wallet has traded historically.
***
## Version compatibility
The SDK targets `https://data-api.polymarket.com`. When the upstream API evolves, validation errors
will highlight mismatched fields. Capture the new payload and submit a PR to keep schemas aligned.
***
# Live Volume
Source: https://polymarket-data.com/data/live-volume
Retrieve live traded volume for a specific event, including per-market totals.
`client.data.misc.getLiveVolume` provides real-time volume for a given event. Each entry includes the
overall total plus per-market amounts.
## Request
```ts theme={null}
const [snapshot] = await client.data.misc.getLiveVolume({ id });
```
### Parameters
| Name | Type | Required | Notes |
| ---- | -------------- | -------- | -------------------- |
| `id` | `number` (≥ 1) | ✅ | Polymarket event ID. |
## Response
```ts theme={null}
type LiveVolume = {
total: number;
markets: Array<{
market: string;
value: number;
}>;
};
```
## Usage example
```ts theme={null}
const [snapshot] = await client.data.misc.getLiveVolume({ id: 35723 });
console.log(`Total volume: ${snapshot.total}`);
snapshot.markets.forEach((entry) => console.log(`${entry.market}: ${entry.value}`));
```
## Failure modes
* `id` must be a positive integer.
# Open Interest
Source: https://polymarket-data.com/data/open-interest
Retrieve open interest totals for market outcome tokens.
`client.data.misc.getOpenInterest` returns open interest metrics for one or more markets. When no
filter is supplied, the API also includes a `GLOBAL` aggregate.
## Request
```ts theme={null}
const entries = await client.data.misc.getOpenInterest(params);
```
### Parameters
| Name | Type | Required | Notes |
| -------- | ---------- | -------- | ------------------------------------- |
| `market` | `string[]` | | Optional condition IDs (0x + 64 hex). |
## Response
```ts theme={null}
type OpenInterest = {
market: string; // condition ID or "GLOBAL"
value: number;
};
```
## Usage example
```ts theme={null}
const entries = await client.data.misc.getOpenInterest({
market: ["0x49252732f0bfe99f2ab09366230607eb9562fa6a56557a10ddcd7dd2198cf588"],
});
entries.forEach((entry) => {
console.log(`${entry.market}: ${entry.value}`);
});
```
## Failure modes
* Condition IDs must be 0x-prefixed 64-hex strings; invalid ones trigger validation errors.
# Positions
Source: https://polymarket-data.com/data/positions
Retrieve a wallet’s open positions, PnL metrics, and market metadata.
`client.data.core.getPositions` surfaces the holdings for a single wallet. Results include token
sizes, average price, cash/percent PnL, redeem/merge flags, and market metadata.
## Request
```ts theme={null}
const positions = await client.data.core.getPositions(params);
```
### Parameters
| Name | Type | Required | Default | Notes |
| --------------- | ---------------------- | -------- | ---------- | --------------------------------------------------------------------------------------------------- |
| `user` | `string` (0x + 40 hex) | ✅ | – | Wallet or proxy address. |
| `market` | `string[]` | | – | Condition IDs (0x + 64 hex). Mutually exclusive with `eventId`. |
| `eventId` | `number[]` | | – | Event IDs. Mutually exclusive with `market`. |
| `sizeThreshold` | `number` | | `1` | Minimum token size to display. |
| `redeemable` | `boolean` | | `false` | Restrict results to redeemable positions. |
| `mergeable` | `boolean` | | `false` | Restrict results to mergeable positions. |
| `limit` | `number` (0–500) | | `100` | Page size. |
| `offset` | `number` (0–10000) | | `0` | Page offset. |
| `sortBy` | enum | | `"TOKENS"` | `CURRENT`, `INITIAL`, `TOKENS`, `CASHPNL`, `PERCENTPNL`, `TITLE`, `RESOLVING`, `PRICE`, `AVGPRICE`. |
| `sortDirection` | enum | | `"DESC"` | `ASC` or `DESC`. |
| `title` | `string` (≤ 100 chars) | | – | Case-insensitive title filter. |
> ⚠️ **Mutually exclusive filters** — Provide either `market` or `eventId`, not both. The SDK throws
> a validation error highlighting both fields if used together.
## Response
```ts theme={null}
type Position = {
proxyWallet: string;
asset: string;
conditionId: string;
size: number;
avgPrice: number;
initialValue: number;
currentValue: number;
cashPnl: number;
percentPnl: number;
totalBought: number;
realizedPnl: number;
percentRealizedPnl: number;
curPrice: number;
redeemable: boolean;
mergeable: boolean;
title: string;
slug: string;
icon: string;
eventSlug: string;
outcome: string;
outcomeIndex: number;
oppositeOutcome: string;
oppositeAsset: string;
endDate: string;
negativeRisk: boolean;
};
```
Unexpected fields are preserved via `passthrough()` so you can adopt new attributes without waiting
for a release.
## Usage example
```ts theme={null}
const positions = await client.data.core.getPositions({
user: "0x56687bf447db6ffa42ffe2204a05edaa20f55839",
limit: 25,
sortBy: "CASHPNL",
});
positions.forEach((position) => {
console.log(`${position.title}: ${position.cashPnl.toFixed(2)} USDC`);
});
```
## Failure modes
* Missing `user` → validation error.
* Conflicting filters → validation error naming both `market` and `eventId`.
* HTTP failure → `HttpError` with `status`, `statusText`, and `body`.
* Network failure → `Error("Network error: …")` with the original `cause`.
# Traded Markets
Source: https://polymarket-data.com/data/traded
Count how many markets a wallet has interacted with historically.
`client.data.misc.getTraded` reports the number of markets in which a wallet has executed trades.
## Request
```ts theme={null}
const traded = await client.data.misc.getTraded({ user });
```
### Parameters
| Name | Type | Required | Notes |
| ------ | ------------------ | -------- | ------------------------ |
| `user` | `string` (address) | ✅ | Wallet or proxy address. |
## Response
```ts theme={null}
{
user: string;
traded: number;
}
```
## Usage example
```ts theme={null}
const traded = await client.data.misc.getTraded({
user: "0x56687bf447db6ffa42ffe2204a05edaa20f55839",
});
console.log(`${traded.user} has traded ${traded.traded} markets`);
```
## Failure modes
* Missing `user` → validation error.
# Trades
Source: https://polymarket-data.com/data/trades
Fetch trade fills with filtering by user, market, side, and thresholds.
`client.data.core.getTrades` returns historical fills across markets. Combine filters to analyse
liquidity, user behaviour, or market conditions.
## Request
```ts theme={null}
const trades = await client.data.core.getTrades(params);
```
### Parameters
| Name | Type | Required | Default | Notes |
| -------------- | -------------------- | -------- | ------- | -------------------------------------------------- |
| `limit` | `number` (0–10000) | | `100` | Page size. |
| `offset` | `number` (0–10000) | | `0` | Page offset. |
| `takerOnly` | `boolean` | | `true` | Set to `false` to include maker fills. |
| `filterType` | `"CASH" \| "TOKENS"` | | – | Must be provided with `filterAmount`. |
| `filterAmount` | `number` (≥ 0) | | – | Minimum cash/tokens threshold. |
| `market` | `string[]` | | – | Condition IDs (mutually exclusive with `eventId`). |
| `eventId` | `number[]` | | – | Event IDs (mutually exclusive with `market`). |
| `user` | `string` (address) | | – | Filter by participant. |
| `side` | `"BUY" \| "SELL"` | | – | Filter by trade direction. |
> ⚠️ Provide **both** `filterType` and `filterAmount` or neither. Mixing them triggers a validation
> error. Likewise, `market` and `eventId` cannot be combined.
## Response
```ts theme={null}
type Trade = {
proxyWallet: string;
side: "BUY" | "SELL";
asset: string;
conditionId: string;
size: number;
price: number;
timestamp: number;
title: string;
slug: string;
icon: string;
eventSlug: string;
outcome: string;
outcomeIndex: number;
name: string;
pseudonym: string;
bio: string;
profileImage: string;
profileImageOptimized: string;
transactionHash: string;
};
```
## Usage example
```ts theme={null}
const trades = await client.data.core.getTrades({
user: "0x56687bf447db6ffa42ffe2204a05edaa20f55839",
side: "BUY",
limit: 20,
});
const averagePrice =
trades.reduce((total, trade) => total + trade.price, 0) / Math.max(trades.length, 1);
```
## Failure modes
* Missing paired filters → validation error referencing both fields.
* Conflicting `market`/`eventId` → validation error.
* HTTP failure → `HttpError` with parsed body.
* Network failure → `Error("Network error: …")` with original cause.
# Portfolio Value
Source: https://polymarket-data.com/data/value
Aggregate the total position value for a wallet across optional markets.
`client.data.core.getValue` aggregates a wallet’s exposure in USDC across all or selected markets.
## Request
```ts theme={null}
const summary = await client.data.core.getValue(params);
```
### Parameters
| Name | Type | Required | Notes |
| -------- | ------------------ | -------- | ------------------------------------------------ |
| `user` | `string` (address) | ✅ | Wallet or proxy address. |
| `market` | `string[]` | | Optional condition IDs to scope the calculation. |
## Response
```ts theme={null}
type UserValue = {
user: string;
value: number;
};
```
The API returns an array, even when querying a single user/market combination.
## Usage example
```ts theme={null}
const [summary] = await client.data.core.getValue({
user: "0x56687bf447db6ffa42ffe2204a05edaa20f55839",
});
console.log(`Total position value: ${summary.value.toFixed(2)} USDC`);
```
## Failure modes
* Missing `user` → validation error.
* Invalid condition ID → validation error referencing the offending index.
# FAQ
Source: https://polymarket-data.com/faq
Frequently asked questions about the polymarket-data SDK.
No. **polymarket-data** is community-maintained and not endorsed by the Polymarket team. It
targets public endpoints published by Polymarket. Confirm contractual or compliance requirements
with Polymarket before deploying to production.
Not for the endpoints currently implemented. If Polymarket introduces authentication, the
community will update the SDK accordingly.
* Node.js 18+ (native `fetch`)
* Serverless runtimes that support ESM modules
* Browser environments, provided CORS allows the target endpoints
Supply a custom `fetch` implementation if your runtime does not expose one.
Every request and response flows through Zod schemas. Unexpected payloads throw descriptive
errors, helping you spot upstream changes immediately.
Zod validation will fail with a message like:
```
Invalid response for gamma.markets.listMarkets: …
```
Capture the new payload, open an issue, and submit a PR updating the schema. Include unit/integration
tests to lock the change in place.
1. Fork the repository.
2. Model the endpoint in Zod.
3. Implement the method and export types.
4. Add unit/integration tests.
5. Run lint, build, and test scripts.
6. Submit a detailed pull request.
Polymarket’s public APIs may enforce rate limits. Cache responses where possible and avoid
excessive polling. Consult Polymarket’s official docs for the latest policies.
# Comment Thread by ID
Source: https://polymarket-data.com/gamma/comments-by-id
Retrieve a specific comment thread via gamma.comments.getCommentById.
`client.gamma.comments.getCommentById` fetches the root comment and its replies for the supplied ID.
## Request
```ts theme={null}
const thread = await client.gamma.comments.getCommentById(id, params);
```
### Parameters
| Name | Type | Required | Notes |
| --------------- | -------------- | -------- | -------------------------------------- |
| `id` | `number` (≥ 0) | ✅ | Comment ID. |
| `get_positions` | `boolean` | | Include position data within profiles. |
## Response
An array of `Comment` objects identical to [`List Comments`](/gamma/comments-list). The first element
is the root comment.
## Usage example
```ts theme={null}
const thread = await client.gamma.comments.getCommentById(1975918, { get_positions: true });
console.log(thread[0]?.body);
```
## Failure modes
* `id` must be numeric.
# Comments by User
Source: https://polymarket-data.com/gamma/comments-by-user
List comments authored by a wallet via gamma.comments.getCommentsByUserAddress.
`client.gamma.comments.getCommentsByUserAddress` collects comments authored by a specific wallet.
## Request
```ts theme={null}
const history = await client.gamma.comments.getCommentsByUserAddress(userAddress, params);
```
### Parameters
| Name | Type | Required | Notes |
| ------------- | ------------------ | -------- | --------------------------------- |
| `userAddress` | `string` (address) | ✅ | Author’s wallet or proxy address. |
| `limit` | `number` (≥ 0) | | Page size. |
| `offset` | `number` (≥ 0) | | Page offset. |
| `order` | `string` | | Sorting expression. |
| `ascending` | `boolean` | | Sort direction. |
## Response
Array of `Comment` objects identical to [`List Comments`](/gamma/comments-list).
## Usage example
```ts theme={null}
const history = await client.gamma.comments.getCommentsByUserAddress(
"0x0b5793a556ceb3a38dcaaa3b262e45decba480cc",
{ limit: 10 },
);
console.log(history.length);
```
## Failure modes
* `userAddress` must be a 0x-prefixed 40-hex string.
* Negative pagination values → validation error.
# List Comments
Source: https://polymarket-data.com/gamma/comments-list
Retrieve event or series comments with optional filters via gamma.comments.listComments.
`client.gamma.comments.listComments` fetches conversations attached to events, series, or markets.
It supports pagination, holder-only views, and optional position visibility.
## Request
```ts theme={null}
const comments = await client.gamma.comments.listComments(params);
```
### Parameters
| Name | Type | Required | Notes |
| -------------------- | --------------------------------- | -------- | ---------------------------------------- |
| `limit` | `number` (≥ 0) | | Page size. |
| `offset` | `number` (≥ 0) | | Page offset. |
| `order` | `string` | | Sorting expression. |
| `ascending` | `boolean` | | Sort direction. |
| `parent_entity_type` | `"Event" \| "Series" \| "market"` | | Filters conversation root. |
| `parent_entity_id` | `number` | | Use with `parent_entity_type`. |
| `get_positions` | `boolean` | | Include position arrays inside profiles. |
| `holders_only` | `boolean` | | Restrict to holders-only comments. |
## Response
```ts theme={null}
type Comment = {
id: string;
body: string | null;
parentEntityType: string | null;
parentEntityID: number | null;
parentCommentID: string | null;
userAddress: string | null;
replyAddress: string | null;
createdAt: string | null;
updatedAt: string | null;
profile?: {
name: string | null;
pseudonym: string | null;
displayUsernamePublic: boolean | null;
bio: string | null;
isMod: boolean | null;
isCreator: boolean | null;
proxyWallet: string | null;
baseAddress: string | null;
profileImage: string | null;
profileImageOptimized?: Record | null;
positions?: Array<{ tokenId: string | null; positionSize: string | null }> | null;
};
reactions?: Array<{
id: string | null;
commentID: number | null;
reactionType: string | null;
icon: string | null;
userAddress: string | null;
createdAt: string | null;
profile?: Comment["profile"];
}> | null;
reportCount: number | null;
reactionCount: number | null;
};
```
## Usage example
```ts theme={null}
const comments = await client.gamma.comments.listComments({
parent_entity_type: "Event",
parent_entity_id: 35723,
limit: 20,
get_positions: true,
});
console.log(comments.map((comment) => comment.body));
```
## Failure modes
* `parent_entity_type` must be `Event`, `Series`, or `market`.
* Negative pagination values → validation error.
# Event by ID
Source: https://polymarket-data.com/gamma/events-by-id
Retrieve detailed event metadata, chats, and nested markets via gamma.events.getEventById.
`client.gamma.events.getEventById` fetches a single event with extensive metadata—market snapshots,
volume metrics, imagery, chat details, and template information.
## Request
```ts theme={null}
const event = await client.gamma.events.getEventById(id, params);
```
### Parameters
| Name | Type | Required | Notes |
| ------------------ | -------------- | -------- | -------------------------- |
| `id` | `number` (≥ 0) | ✅ | Event ID. |
| `include_chat` | `boolean` | | Include chat metadata. |
| `include_template` | `boolean` | | Include template metadata. |
## Response
The API returns a single `Event` object. Fields match those surfaced by the Polymarket app: titles,
descriptions, imagery, liquidity/volume metrics, nested markets, tags, chat rooms, and more.
## Usage example
```ts theme={null}
const event = await client.gamma.events.getEventById(35723, {
include_chat: true,
include_template: true,
});
console.log(event.title, event.markets?.length);
```
## Failure modes
* `id` must be numeric.
# Event by Slug
Source: https://polymarket-data.com/gamma/events-by-slug
Retrieve an event using its slug via gamma.events.getEventBySlug.
`client.gamma.events.getEventBySlug` fetches the same rich event payload as `getEventById`, using the
human-readable slug.
## Request
```ts theme={null}
const event = await client.gamma.events.getEventBySlug(slug, params);
```
### Parameters
| Name | Type | Required | Notes |
| ------------------ | --------- | -------- | -------------------------------------------------------------------- |
| `slug` | `string` | ✅ | Event slug (e.g., `"chile-presidential-election-1st-round-winner"`). |
| `include_chat` | `boolean` | | Include chat metadata. |
| `include_template` | `boolean` | | Include template metadata. |
## Response
A single `Event` object identical to [`Event by ID`](/gamma/events-by-id).
## Usage example
```ts theme={null}
const event = await client.gamma.events.getEventBySlug(
"chile-presidential-election-1st-round-winner",
{ include_chat: true },
);
console.log(event.title);
```
## Failure modes
* `slug` must be a non-empty string.
# Event Tags
Source: https://polymarket-data.com/gamma/events-tags
Retrieve tag metadata for an event via gamma.events.getEventTags.
`client.gamma.events.getEventTags` lists the tags associated with an event.
## Request
```ts theme={null}
const tags = await client.gamma.events.getEventTags(id);
```
### Parameters
| Name | Type | Required | Notes |
| ---- | -------------- | -------- | --------- |
| `id` | `number` (≥ 0) | ✅ | Event ID. |
## Response
```ts theme={null}
type EventTag = {
id: string;
label: string | null;
slug: string | null;
forceShow: boolean | null;
publishedAt: string | null;
createdBy: number | null;
updatedBy: number | null;
createdAt: string | null;
updatedAt: string | null;
forceHide: boolean | null;
isCarousel: boolean | null;
};
```
## Usage example
```ts theme={null}
const tags = await client.gamma.events.getEventTags(35723);
console.log(tags.map((tag) => tag.slug));
```
## Failure modes
* `id` must be numeric.
# Overview
Source: https://polymarket-data.com/gamma/index
Discover Polymarket’s discovery-focused endpoints exposed via client.gamma.*.
The `client.gamma` namespace taps into the data behind the Polymarket web app—search, comments,
series, markets, events, and sports metadata. These endpoints are ideal for discovery surfaces,
community tooling, and analytics.
League rosters, team branding, and imagery.
Full-text search across events, tags, and user profiles.
Event and series conversations with profile metadata.
Collections of related events, with optional chat data.
Comprehensive catalogue with advanced filtering and analytics fields.
Rich event metadata, tags, chat info, and nested markets.
> **Schema guarantee:** Gamma endpoints also leverage Zod validation, so payload changes are
> surfaced immediately with descriptive errors.
***
# Markets
Source: https://polymarket-data.com/gamma/markets
Explore the Polymarket market catalogue via gamma.markets.listMarkets.
`client.gamma.markets.listMarkets` is the powerhouse endpoint behind Polymarket’s catalogue. Filter
markets by IDs, liquidity, volume, dates, tags, sports metadata, and more.
## Request
```ts theme={null}
const markets = await client.gamma.markets.listMarkets(params);
```
### Parameters
| Name | Type | Required | Notes |
| ----------------------- | -------------- | -------- | -------------------------------------------------------- |
| `limit` | `number` (≥ 0) | | Page size. |
| `offset` | `number` (≥ 0) | | Page offset. |
| `order` | `string` | | Sort expression (comma-separated). |
| `ascending` | `boolean` | | Sort direction. |
| `id` | `number[]` | | Filter by market IDs. |
| `slug` | `string[]` | | Filter by market slugs. |
| `clob_token_ids` | `string[]` | | Filter by CLOB token IDs. |
| `condition_ids` | `string[]` | | Filter by condition IDs (0x + 64 hex). |
| `market_maker_address` | `string[]` | | Filter by AMM contract addresses. |
| `liquidity_num_min/max` | `number` | | Liquidity range. |
| `volume_num_min/max` | `number` | | Volume range. |
| `start_date_min/max` | `string` (ISO) | | Start-date range filters. |
| `end_date_min/max` | `string` (ISO) | | End-date range filters. |
| `tag_id` | `number` | | Filter by tag ID. |
| `related_tags` | `boolean` | | Include related tags. |
| `cyom` | `boolean` | | Filter Create-Your-Own markets. |
| `uma_resolution_status` | `string` | | Filter by UMA status. |
| `game_id` | `string` | | Filter by sports game ID. |
| `sports_market_types` | `string[]` | | Filter by sports perspectives (moneyline, spread, etc.). |
| `rewards_min_size` | `number` | | Minimum rewards size. |
| `question_ids` | `string[]` | | Filter by question IDs. |
| `include_tag` | `boolean` | | Include tag metadata. |
| `closed` | `boolean` | | Filter by closed status. |
> ℹ️ **Date formats** — Provide ISO8601 strings (e.g., `2025-11-16T00:00:00Z`). Strings are parsed
> via `Date.parse` and invalid values trigger validation errors.
## Response
`Market[]` with hundreds of fields (title, question, outcomes, liquidity/volume metrics, tags,
series references, etc.). All numeric metrics are parsed as numbers.
## Usage example
```ts theme={null}
const markets = await client.gamma.markets.listMarkets({
closed: false,
liquidity_num_min: 1000,
limit: 10,
});
console.log(markets.map((market) => market.title ?? market.slug));
```
## Failure modes
* Invalid dates or malformed IDs → validation errors with detailed paths.
# Public Search
Source: https://polymarket-data.com/gamma/search-public
Perform full-text search across events, tags, and profiles via gamma.search.publicSearch.
`client.gamma.search.publicSearch` powers discovery in the Polymarket app. Query events, tags, and
user profiles with sophisticated filters.
## Request
```ts theme={null}
const results = await client.gamma.search.publicSearch(params);
```
### Parameters
| Name | Type | Required | Default | Notes |
| --------------------- | -------------- | -------- | ------- | ------------------------------------- |
| `q` | `string` | ✅ | – | Query string. |
| `cache` | `boolean` | | – | Enable cached responses. |
| `events_status` | `string` | | – | Filter events by status. |
| `limit_per_type` | `number` (≥ 0) | | – | Result cap per section. |
| `page` | `number` (≥ 0) | | – | Pagination control. |
| `events_tag` | `string[]` | | – | Include events with these tag slugs. |
| `keep_closed_markets` | `number` (≥ 0) | | – | Retain closed markets. |
| `sort` | `string` | | – | Sorting expression. |
| `ascending` | `boolean` | | – | Sort direction. |
| `search_tags` | `boolean` | | – | Toggle tag section. |
| `search_profiles` | `boolean` | | – | Toggle profile section. |
| `recurrence` | `string` | | – | Filter by recurrence (e.g., `daily`). |
| `exclude_tag_id` | `number[]` | | – | Tag IDs to exclude. |
| `optimized` | `boolean` | | – | Request optimised payload. |
## Response
```ts theme={null}
type SearchResponse = {
events: Event[] | null | undefined;
tags: Tag[] | null | undefined;
profiles: Profile[] | null | undefined;
pagination: { hasMore: boolean; totalResults: number };
};
```
Each section contains rich metadata—titles, imagery, volume stats, chat info, and more. Check for
`null`/`undefined` before iterating.
## Usage example
```ts theme={null}
const search = await client.gamma.search.publicSearch({
q: "election",
search_tags: true,
search_profiles: true,
limit_per_type: 10,
});
console.log(search.events?.map((event) => event.title));
```
## Failure modes
* Missing `q` → validation error.
* Negative pagination values → validation error.
# Series by ID
Source: https://polymarket-data.com/gamma/series-by-id
Retrieve a single Polymarket series with optional chat data via gamma.series.getSeriesById.
`client.gamma.series.getSeriesById` fetches a specific series, including nested events, chat details,
and tags.
## Request
```ts theme={null}
const [series] = await client.gamma.series.getSeriesById(id, params);
```
### Parameters
| Name | Type | Required | Notes |
| -------------- | -------------- | -------- | ---------------------- |
| `id` | `number` (≥ 0) | ✅ | Series ID. |
| `include_chat` | `boolean` | | Include chat metadata. |
## Response
An array containing one `Series` object (consistent with the upstream API). Fields match the
structure returned by [`List Series`](/gamma/series-list).
## Usage example
```ts theme={null}
const [series] = await client.gamma.series.getSeriesById(10388, { include_chat: true });
console.log(series.title);
```
## Failure modes
* `id` must be numeric.
# List Series
Source: https://polymarket-data.com/gamma/series-list
Browse Polymarket series collections with optional filters via gamma.series.listSeries.
`client.gamma.series.listSeries` returns series metadata, including nested events, categories, tags,
and optional chat data.
## Request
```ts theme={null}
const series = await client.gamma.series.listSeries(params);
```
### Parameters
| Name | Type | Required | Default | Notes |
| ------------------- | -------------- | -------- | ------- | ------------------------------------- |
| `limit` | `number` (≥ 0) | | – | Page size. |
| `offset` | `number` (≥ 0) | | – | Page offset. |
| `order` | `string` | | – | Sort expression. |
| `ascending` | `boolean` | | – | Sort direction. |
| `slug` | `string[]` | | – | Filter by series slug(s). |
| `categories_ids` | `number[]` | | – | Filter by category IDs. |
| `categories_labels` | `string[]` | | – | Filter by category labels. |
| `closed` | `boolean` | | – | Filter by closed status. |
| `include_chat` | `boolean` | | – | Include chat metadata. |
| `recurrence` | `string` | | – | Filter by recurrence (e.g., `daily`). |
## Response
Each entry matches the `Series` type exported by the SDK, containing fields such as `title`,
`seriesType`, `tags`, `chats`, and nested `events` arrays.
## Usage example
```ts theme={null}
const dailySeries = await client.gamma.series.listSeries({ recurrence: "daily", limit: 5 });
console.log(dailySeries.map((entry) => entry.title));
```
## Failure modes
* Empty array filters (e.g., `slug: []`) trigger validation errors.
# List Teams
Source: https://polymarket-data.com/gamma/sports-list-teams
Retrieve team rosters, leagues, and branding assets via gamma.sports.listTeams.
`client.gamma.sports.listTeams` exposes the teams tracked by Polymarket across supported leagues.
Use it to populate dropdowns, leaderboards, or sports dashboards.
## Request
```ts theme={null}
const teams = await client.gamma.sports.listTeams(params);
```
### Parameters
| Name | Type | Required | Default | Notes |
| -------------- | -------------- | -------- | ------- | --------------------------------------------- |
| `limit` | `number` (≥ 0) | | – | Number of results. |
| `offset` | `number` (≥ 0) | | – | Pagination offset. |
| `order` | `string` | | – | Comma-separated fields to sort by. |
| `ascending` | `boolean` | | – | Sort direction. |
| `league` | `string[]` | | – | Filter by league identifiers (e.g., `"NBA"`). |
| `name` | `string[]` | | – | Filter by team names. |
| `abbreviation` | `string[]` | | – | Filter by abbreviations. |
## Response
```ts theme={null}
type Team = {
id: number;
name: string | null;
league: string | null;
record: string | null;
logo: string | null;
abbreviation: string | null;
alias: string | null;
createdAt: string | null;
updatedAt: string | null;
providerId: number | null;
};
```
## Usage example
```ts theme={null}
const nbaTeams = await client.gamma.sports.listTeams({ league: ["NBA"], limit: 50 });
nbaTeams.forEach((team) => console.log(team.name));
```
## Failure modes
* Numeric parameters must be non-negative.
* Empty arrays (e.g., `league: []`) trigger validation errors.
# Sports Metadata
Source: https://polymarket-data.com/gamma/sports-metadata
Fetch imagery, resolution sources, and tagging metadata via gamma.sports.getSportsMetadata.
`client.gamma.sports.getSportsMetadata` returns branding assets and contextual information for each
sport tracked by Polymarket. Ideal for enriching market tiles with official logos and resolution
links.
## Request
```ts theme={null}
const metadata = await client.gamma.sports.getSportsMetadata();
```
No parameters are required.
## Response
```ts theme={null}
type SportsMetadata = {
sport: string;
image: string;
resolution: string;
ordering: string;
tags: string; // comma-separated tag IDs
series: string; // series identifier
};
```
## Usage example
```ts theme={null}
const sports = await client.gamma.sports.getSportsMetadata();
sports.forEach((entry) => {
console.log(`${entry.sport} resolves at ${entry.resolution}`);
});
```
## Failure modes
Network/HTTP failures propagate per the [architecture contract](/architecture#error-handling-contract).
# Introduction
Source: https://polymarket-data.com/index
Welcome to polymarket-data, the community TypeScript SDK for Polymarket APIs.
Welcome to **polymarket-data**, the community-maintained TypeScript SDK for Polymarket’s public
APIs.
> This SDK is built by independent contributors and is **not officially affiliated with the
> Polymarket team**. Always validate behaviour against Polymarket’s public documentation before
> deploying production systems.
Install the SDK, configure endpoints, and run your first health check.
***
## What’s in the box?
Every request/response is validated with Zod for runtime and IDE safety.
Examples are exercised against the live Polymarket APIs for accuracy.
***
## Conceptual Diagram
```mermaid theme={null}
flowchart TD
A[Polymarket APIs]
%% Core data endpoints
A -->|Data Endpoint| D[Core Data APIs]
A -->|Data Endpoint| M[Misc Data APIs]
A -->|Data Endpoint| H[Health Check]
%% Gamma section
A -->|Gamma Endpoint| G[Gamma APIs]
%% Gamma submodules
G --> GM[Markets]
G --> GE[Events]
G --> GR[Series]
G --> GC[Comments]
G --> GS[Sports]
G --> GQ[Search]
%% Style tweaks
classDef main fill:#151b28,stroke:#7ab2f8,stroke-width:1px,color:#fff;
classDef sub fill:#212d40,stroke:#7ab2f8,stroke-width:0.5px,color:#fff;
class A main;
class D,H,M,G,GM,GE,GR,GC,GS,GQ sub;
```
The `Polymarket` constructor spins up **two** HTTP clients, one targeting the data endpoint and one
for the gamma endpoint. Each method inherits common validation and error handling layers.
***
## Ready to build?
Positions, trades, activity, holders, and value analytics.
Search, comments, series, markets, and events intelligence.
Happy building—and thanks for contributing to the broader Polymarket ecosystem.
# Quickstart
Source: https://polymarket-data.com/quickstart
Install polymarket-data, configure the client, and ship your first integration.
Get up and running with **polymarket-data** in minutes. This guide walks through installation,
configuration, and your first live requests.
```bash theme={null}
npm install polymarket-data
# or
pnpm add polymarket-data
yarn add polymarket-data
```
The package ships as ESM with bundled TypeScript declarations.
```ts theme={null}
import { Polymarket } from "polymarket-data";
const client = new Polymarket();
```
### Optional configuration
| Option | Description | Default |
| --------------- | -------------------------------------------- | ---------------------------------- |
| `dataEndpoint` | Base URL for the classic data API. | `https://data-api.polymarket.com` |
| `gammaEndpoint` | Base URL for the gamma API. | `https://gamma-api.polymarket.com` |
| `fetch` | Custom Fetch implementation (for SSR/tests). | `globalThis.fetch` |
```ts theme={null}
const client = new Polymarket({
dataEndpoint: "https://custom-data.polymarket.com",
gammaEndpoint: "https://custom-gamma.polymarket.com",
fetch: myCustomFetch,
});
```
> **Mocking in tests** — pass a stubbed `fetch` that returns predefined payloads. All methods
> pipe through the injected fetch before validation.
```ts theme={null}
const status = await client.health();
console.log(status); // { data: "OK" }
```
If this call fails, verify network access and endpoint URLs. The SDK throws `HttpError` for API
failures and `Error("Network error: …")` for connectivity issues.
```ts theme={null}
// Portfolio analytics
const positions = await client.data.core.getPositions({
user: "0x56687bf447db6ffa42ffe2204a05edaa20f55839",
limit: 10,
});
// Market discovery
const markets = await client.gamma.markets.listMarkets({
closed: false,
liquidity_num_min: 1000,
limit: 5,
});
```
Use named imports for types:
```ts theme={null}
import type { Position, Market } from "polymarket-data";
```
Explore positions, trades, activity, holders, and value endpoints.
Discover search, comments, series, markets, and events modules.