# Activity Source: https://docs.datadash.xyz/activity Every prediction-market fill, enriched with market, event and category metadata. Activity is the chronological log of prediction-market trades. Every row is a single fill — one wallet buying or selling one position — already joined to the market, event, category and series it belongs to, so you don't have to resolve identifiers yourself. The same endpoint also returns a **summary** view, grouping fills into time buckets when you don't want the raw log. ![Activity](https://mintcdn.com/datadash/uRkQ3Pi05HluLNHT/images/activity.png?fit=max\&auto=format\&n=uRkQ3Pi05HluLNHT\&q=85\&s=baeafe45d343a5fd9c682bdfbeb9b8c8) The activity feed, rolled up to a one-hour window. Expanding a row charts the market's price around the fill. ## Columns | Column | Meaning | | - | - | | **`activity`** | The type of activity: a buy or a sell. | | **`timestamp`** | When the fill occurred. | | **`user`** | The wallet that traded. | | **`amount`** | Shares bought or sold. | | **`usdPrice`** | Price per share, in USD. | | **`usdAmount`** | USD value of the fill. | | **`avgBuyingPrice`** | The wallet's average buying price at the time of this fill. | | **`realizedPnl`** | Realized profit and loss, in USD. | | **`realizedPnlPercentage`** | Realized PnL as a percentage of cost basis. | | **`token`** | The [position](/position-ids) traded. | | **`market`** | The market the fill happened in. | | **`event`** | The parent event of that market. | | **`tags`** | Categories on the event. | | **`series`** | The series the event belongs to. | | **`txHash`** | On-chain transaction hash. | | **`seqId`** | Sequence id, for stable ordering. | The reference columns are what make the log *enriched*. Each comes back as the resolved entity rather than a bare id, so a row already carries the market's question, the event's title and the category labels: ```json theme={null} { "market": { "id": 1234, "question": "Will X win?", "closed": false }, "user": { "userId": "0xAb8D...90F1", "displayName": "..." }, "tags": [ { "id": 7, "label": "Politics" }, { "id": 9, "label": "US" } ] } ``` Resolution is one level deep — see [Resolved references](/filters#resolved-references). > [!NOTE] > > You still **filter** on the id fields — `marketId`, `eventId`, `tagIds`, `seriesId` and `positionId` — even though rows come back carrying the resolved entity. See [Filtering](/filters). ## Two ways to read it ### The log By default the endpoint returns **one row per fill**, newest first. ```json theme={null} { "page": { "limit": 50 }, "filter": [{ "field": "wallet", "operator": "eq", "value": "0xAb8D...90F1" }] } ``` ### The summary Pass `aggregationWindow` to roll fills up into time buckets. Rows are grouped by **bucket, activity type, wallet and position** — one row per wallet's buying (or selling) of one position within one window. ```json theme={null} { "page": { "limit": 50 }, "aggregationWindow": 4, "activityIds": [1], "filter": [{ "field": "wallet", "operator": "eq", "value": "0xAb8D...90F1" }] } ``` Grains run from hourly to monthly; the API Reference lists the id for each. Omit the field for the raw log. > [!NOTE] > > Measures are aggregated the way each one means something: `amount`, > `usdAmount` and `realizedPnl` are **summed**, while `usdPrice` and > `avgBuyingPrice` are **share-weighted averages** — not plain averages, so a > large fill counts more than a small one. `market`, `event`, `tags` and > `series` carry through as representative values for the group. ## Selecting activity types `activityIds` restricts the log to buys or sells. Activity type isn't part of `filter` — it's selected here. ```json theme={null} { "page": { "limit": 50 }, "activityIds": [1] } ``` All types are returned when omitted. See [Filtering](/filters#activity-options) for how these fields interact with the rest of the request. ## Filtering and search Filter on wallet, market, event, category, position, timestamp, and the numeric measures — see [Filtering](/filters) for the syntax. `searchKey` runs a free-text search over markets, combining semantic and keyword relevance, so you can find activity by what a market is about rather than by id. ```json theme={null} { "page": { "limit": 50 }, "searchKey": "election", "filter": [{ "field": "usdAmount", "operator": "gte", "value": 1000 }], "orderBy": [{ "field": "timestamp", "direction": "desc" }] } ``` ## API endpoint > [card] [Activity](/api-reference) > > `POST /api/v1/activity`: chronological log of buys and sells, or a bucketed > summary. # API Keys Source: https://docs.datadash.xyz/api-keys Authenticate your requests to the Datadash API. Every API request must be authenticated with an API key, sent in the `X-Api-Key` header. ```bash theme={null} curl -X POST https://api.datadash.xyz/api/v1/positions/active \ -H "X-Api-Key: $DATADASH_API_KEY" \ -H "Content-Type: application/json" \ -d '{"page": {"limit": 50}, "filter": [{"field": "userId", "operator": "eq", "value": "0xAb8D...90F1"}]}' ``` Requests without a key, or with a revoked or malformed one, return `401`: ```json theme={null} { "code": "unauthenticated", "message": "missing credentials: supply an X-Api-Key header or a bearer token" } ``` Keys are managed from the [API Keys](https://datadash.xyz/settings/api-keys) page in the dashboard. You can also reach it from the wallet menu in the top-right corner, under **API Keys**. ## Creating a key **1. Open the API Keys page** Sign in at [datadash.xyz](https://datadash.xyz) and go to [Settings → API Keys](https://datadash.xyz/settings/api-keys). **2. Name the key** Click **Create key** and give it a name, like `production`. Names are 1–30 characters, **letters and digits only**, with no spaces, dashes or underscores. Each name has to be unique within your account. **3. Copy the key** The key is shown once. Click **Copy**, store it somewhere safe, then click **Done**. ```bash theme={null} export DATADASH_API_KEY="datadash_AGB1c2VyXzAxSFEy..." ``` > [!WARNING] > > The key is shown **once, at creation**. Datadash stores only a hash of it and can never show it to you again. If you lose it, revoke the key and create a new one. ## Viewing your keys The API Keys page lists each key's name, last three characters, and creation date. That's enough to tell your keys apart without exposing them. ## Revoking a key Click the trash icon next to a key and confirm with **Revoke key**. Revocation takes effect within a few seconds across all servers, and every later request with that key returns `401`. You can't undo a revocation. ## Keeping keys safe * **Never ship a key in client-side code.** Anything in a browser, mobile app, or public repository is readable by anyone. Call the API from your own server instead. * **Use one key per environment or service.** If a key leaks, you revoke just that one instead of breaking everything at once. * **Load keys from environment variables or a secret manager**, not from source. * **Rotate on exposure.** Create the replacement, switch traffic to it, then revoke the old key. > [!NOTE] > > A key carries the full access of the account that created it. Treat it like a password. ## Next steps > [card] [Filtering](/filters) > > Narrow any list endpoint with typed conditions and AND/OR groups. > [card] [Generate a client](/openapi-clients) > > Build a typed TypeScript or Python client from the OpenAPI spec. # Enriched Activities Source: https://docs.datadash.xyz/api-reference/activity/enriched-activities /openapi.json post /api/v1/activity Chronological log of prediction-market trades (buys and sells), one row per fill, enriched with market, event, category and series metadata. # Create a cohort Source: https://docs.datadash.xyz/api-reference/cohorts/create-a-cohort /openapi.json post /api/v1/cohorts Defines a cohort from criteria. Membership is computed in the background, so the cohort is not usable until GET reports it ready. # Delete a cohort Source: https://docs.datadash.xyz/api-reference/cohorts/delete-a-cohort /openapi.json delete /api/v1/cohorts/{cohortId} Deletes a cohort. Insights and endpoints already referencing it keep working against its last computed membership. # Get a cohort Source: https://docs.datadash.xyz/api-reference/cohorts/get-a-cohort /openapi.json get /api/v1/cohorts/{cohortId} Reports a cohort's build status and size. Poll this after create or update. # Update a cohort Source: https://docs.datadash.xyz/api-reference/cohorts/update-a-cohort /openapi.json patch /api/v1/cohorts/{cohortId} Changes a cohort's name or replaces its criteria. Only the fields sent are changed; supplying groups replaces the criteria wholesale and rebuilds the cohort. # Active Market Holder Source: https://docs.datadash.xyz/api-reference/holders/active-market-holder /openapi.json post /api/v1/market-holders/active User-level holders of currently-held (active) market positions. # All Market Holder Source: https://docs.datadash.xyz/api-reference/holders/all-market-holder /openapi.json post /api/v1/market-holders/all User-level holders across all markets, with nested token details. # Closed Market Holder Source: https://docs.datadash.xyz/api-reference/holders/closed-market-holder /openapi.json post /api/v1/market-holders/closed User-level holders of closed (exited) market positions. # Active Position Source: https://docs.datadash.xyz/api-reference/positions/active-position /openapi.json post /api/v1/positions/active Currently held (open) positions with unrealized PnL for a wallet or cohort. One row per position token; open (unresolved) markets only. # All Positions Source: https://docs.datadash.xyz/api-reference/positions/all-positions /openapi.json post /api/v1/positions/all All positions (open and closed) for a wallet or cohort, grouped by event; the nested positions field carries the per-position breakdown. # Closed Positions Source: https://docs.datadash.xyz/api-reference/positions/closed-positions /openapi.json post /api/v1/positions/closed Closed (exited) positions for a wallet or cohort, grouped by event. # User Position Source: https://docs.datadash.xyz/api-reference/positions/user-position /openapi.json post /api/v1/user-position Lifetime per-position trading stats for a wallet, bought/sold shares and USD, entry/exit prices, realized and unrealized PnL. One row per (wallet, position token); see positions/all for the event-grouped portfolio view. # User Profile Source: https://docs.datadash.xyz/api-reference/profiles/user-profile /openapi.json post /api/v1/profiles/user Per-wallet performance profile, PnL, win rate, volume, ROI, hold time and trade counts, one row per wallet for the requested duration. # User Tag Profile Source: https://docs.datadash.xyz/api-reference/profiles/user-tag-profile /openapi.json post /api/v1/profiles/user-tag Per-wallet performance broken down by category tag, PnL, win rate, volume and ROI per (wallet, tag) for the requested duration. # Signal Source: https://docs.datadash.xyz/api-reference/signals/signal /openapi.json post /api/v1/signals/scores Per-wallet, per-position insider signal scores for currently-held legs in active markets. # Global Smart Money Source: https://docs.datadash.xyz/api-reference/smart-money/global-smart-money /openapi.json post /api/v1/smart-money/global Markets ranked by smart-money edge across the selected wallet set. # Smart Money Holders Source: https://docs.datadash.xyz/api-reference/smart-money/smart-money-holders /openapi.json post /api/v1/smart-money/holders Per-wallet smart-money holders of one position — one side of one market — within an event. Ask for the other side with the sibling position id. # Smart Money Summary Source: https://docs.datadash.xyz/api-reference/smart-money/smart-money-summary /openapi.json post /api/v1/smart-money/summary Smart-money Yes/No summary of an event, one row per open market. Add a Market filter to get the single row a market's strip renders. # Cohorts Source: https://docs.datadash.xyz/cohorts Track and analyze groups of wallets. A cohort is a named group of wallets you track and analyze together. Cohorts are the lens for the rest of Datadash: point [Smart Money](/smart-money) or [Signals](/signals) at a cohort and every view is scoped to just those wallets. > [card] [What is a cohort?](https://datadash.xyz/blog/polymarket-cohorts) > > Static and dynamic cohorts, rule recipes from our featured cohorts, and how cohorts feed Signals, Smart Money and alerts. ## Static and rule-based cohorts A cohort's members can be defined two ways: * **Static**: an explicit list of wallets you add by hand. * **Rule-based**: criteria that automatically match wallets and refresh over time. Rules combine portfolio properties and performance windows, for example: > Users in ***Tennis*** category where $totalPnl \geq 100,000 \;and\; winRate \geq 70 %$ during **Last Year** Rule-based cohorts re-evaluate on a schedule; each cohort shows when it was last refreshed. Cohorts are either **Featured** (curated and shared, such as "High Stakes Traders" or "Crypto Whales") or **Private** (yours alone). ## The cohort view Every cohort opens on a set of headline stats, then a leaderboard of its wallets: > [card] Traders > > Number of wallets in the cohort. > [card] Total PnL > > Combined realized profit and loss across the cohort. > [card] ROI > > Return on investment for the selected window. > [card] Total Volume > > Total trading volume across the cohort. The leaderboard ranks each wallet by PnL, ROI, win rate, positions, profit factor, volume and hold time, over a selectable window (1D, 1W, 1M, 1Y, or all time). Additional tabs break the same cohort down by **Portfolio** (open and closed positions), **Activity** (the trade log), **Category** (performance per tag), **Signals** (the cohort's highest-conviction bets), and **Smart Money** (how the cohort leans on every market compared with the live price). ## Cohort IDs A cohort ID is a TSID — 13 characters of Crockford base32 (`I`, `L`, `O` and `U` are excluded): ``` ^[0-9A-HJ-KM-NP-TV-Z]{13}$ ``` For example `0J9XQ4M7B2K5T`. IDs are time-sortable, so ordering by ID orders by creation. ## API endpoints Cohort analytics are served by the profiles endpoints, scoped to the cohort's wallets. The positions, activity, signals and smart money endpoints back the corresponding tabs. > [card] [User Profile](/api-reference) > > `POST /api/v1/profiles/user`: per-wallet PnL, win rate, volume, ROI, hold time and trade counts. > [card] [User Tag Profile](/api-reference) > > `POST /api/v1/profiles/user-tag`: the same performance broken down by category tag. # Filtering Source: https://docs.datadash.xyz/filters Narrow any list endpoint with typed conditions and AND/OR groups. Every list endpoint accepts an optional `filter` in the request body. It's a **list of conditions, combined with AND**. ```json theme={null} { "page": { "limit": 50 }, "filter": [ { "field": "userId", "operator": "eq", "value": "0xAb8D...90F1" }, { "field": "value", "operator": "gte", "value": 1000 } ] } ``` That returns positions belonging to that wallet **and** worth at least \$1,000. To express OR, use a [group](#groups). Fields are addressed by the same names you get back in the response, so you filter on what you see. Each endpoint documents its own filterable fields and the operators each accepts — see the [API Reference](/api-reference). ## Conditions A condition names a `field`, an `operator`, and a `value`. ```json theme={null} { "field": "unrealizedPnl", "operator": "gt", "value": 500 } ``` Because conditions are list items rather than object keys, you can use **the same field as many times as you like** — for example, to bound a value on both sides: ```json theme={null} "filter": [ { "field": "value", "operator": "gte", "value": 1000 }, { "field": "value", "operator": "lte", "value": 5000 } ] ``` ### Operators by field type | Field type | Operators | Value | | - | - | - | | Numbers | `eq` `neq` `gt` `gte` `lt` `lte` | a number | | Categories & IDs | `in` `notIn` | one value, or an array | | Text | `in` `notIn` `matches` `notMatches` | `matches` takes one search term | | Wallet addresses | the text operators, plus `inCohort` `notInCohort` | addresses, or cohort ids | | Booleans | `eq` | `true` or `false` | | Timestamps | `last` `between` `since` | see [Time ranges](#time-ranges) | > [!NOTE] > > `in` and `notIn` accept either a single value or an array — `"value": 1234` and `"value": [1234, 5678]` both work. ID fields such as `marketId` and `eventId` take **integers**; text fields take strings. ### Wallet addresses and cohorts Address fields accept a list of addresses, or a [cohort](/cohorts) to filter by membership: ```json theme={null} { "field": "userId", "operator": "inCohort", "value": ["01HQ2K..."] } ``` Use `notInCohort` to return everything outside the cohort. ### Time ranges ```json theme={null} { "field": "timestamp", "operator": "last", "value": { "unit": "day", "length": 7 } } { "field": "timestamp", "operator": "between", "value": { "from": "2026-01-01", "to": "2026-03-31" } } { "field": "timestamp", "operator": "since", "value": "2026-01-01" } { "field": "timestamp", "operator": "since", "value": { "range": "month" } } ``` `last` accepts `day`, `week`, `month`, `quarter`, `year`. `since` takes either a date or a calendar `range` (`week`, `month`, `quarter`, `year`). ## Groups The top-level list is always AND. For OR, add a **group** — an item with an `operator` (`AND` or `OR`) and its own `filters`. ```json theme={null} "filter": [ { "field": "userId", "operator": "eq", "value": "0xAb8D...90F1" }, { "operator": "OR", "filters": [ { "field": "value", "operator": "gte", "value": 1000 }, { "field": "unrealizedPnl", "operator": "gt", "value": 500 } ] } ] ``` That reads as: **that wallet**, AND (**value ≥ 1000** OR **PnL > 500**). To make the whole query an OR, pass a single group: ```json theme={null} "filter": [ { "operator": "OR", "filters": [ { "field": "value", "operator": "gte", "value": 1000 }, { "field": "unrealizedPnl", "operator": "gt", "value": 500 } ] } ] ``` > [!WARNING] > > Groups nest at most two levels deep. A group may contain groups, but those inner groups must contain only conditions. ## A complete request ```bash theme={null} curl -X POST https://api.datadash.xyz/api/v1/positions/active \ -H "X-Api-Key: $DATADASH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "page": { "offset": 0, "limit": 50 }, "filter": [ { "field": "userId", "operator": "eq", "value": "0xAb8D...90F1" }, { "field": "value", "operator": "gte", "value": 1000 }, { "field": "value", "operator": "lte", "value": 5000 }, { "operator": "OR", "filters": [ { "field": "marketId", "operator": "in", "value": [1234, 5678] }, { "field": "unrealizedPnl", "operator": "gt", "value": 500 } ] } ], "orderBy": [{ "field": "value", "direction": "desc" }] }' ``` ## Resolved references Reference fields come back as the resolved entity rather than a bare id, so you don't need a second request to turn an id into a name. Resolution is **one level deep** — a resolved row keeps its own references as plain ids, so responses can't fan out across the graph. The [API Reference](/api-reference) shows what each endpoint resolves. ## Activity options The [activity](/api-reference) endpoint takes two extra fields that aren't filters, because they change *which* rows are built rather than narrowing the ones returned. ### Selecting activity types `activityIds` restricts the log to certain activity types. The activity column isn't part of `filter` — it's selected here instead. ```json theme={null} { "page": { "limit": 50 }, "activityIds": [1] } ``` All activity types are returned when omitted. The API Reference lists each id and its name for the endpoint. ### Aggregating into buckets By default the endpoint returns **one row per event**. Pass `aggregationWindow` to get rows **grouped by time bucket, activity type, and wallet** instead — a summary rather than a log. ```json theme={null} { "page": { "limit": 50 }, "aggregationWindow": 4, "activityIds": [1], "filter": [ { "field": "wallet", "operator": "eq", "value": "0xAb8D...90F1" } ] } ``` Each row then covers one wallet's activity of one type within one bucket, with the measures aggregated over that window. The available grains — hourly through monthly — are listed in the API Reference; omit the field for the unaggregated log. > [!NOTE] > > `activityIds` and `aggregationWindow` apply only to the activity endpoint. Sending them anywhere else returns `400`. ## Required filters Some endpoints require a filter on a particular field. The position and holder endpoints, for example, require `userId` — every query must be scoped to a wallet or a cohort. Omitting one returns `400`. ## Errors Filter problems come back as `400` with a machine-readable code and a message naming the field. ```json theme={null} { "code": "invalid_argument", "message": "filter: unknown field \"markt\"" } ``` | Message | Cause | | - | - | | `unknown field "…"` | The field doesn't exist on this endpoint, or is misspelled. | | `field "…" is not filterable` | The field is returned in responses but can't be filtered on. | | `unsupported operator "…"` | The operator doesn't apply to that field's type. | | `expected a list of conditions and groups` | `filter` was sent as an object instead of a list. | | `a condition must name a field` | An item has neither a `field` nor nested `filters`. | | `value is required` | The condition is missing its value. | | `group operator must be "AND" or "OR"` | A group with several members didn't say how to combine them. | | `groups can be nested at most 2 levels deep` | Too much nesting. | | `unknown activity …` / `unknown window …` | An `activityIds` or `aggregationWindow` value the endpoint doesn't define. | | `only supported by the activity endpoint` | `activityIds` or `aggregationWindow` sent to another endpoint. | # Holders Source: https://docs.datadash.xyz/holders Who holds an event's outcomes, with per-wallet totals and outcome-level detail. Holders answers "who is in this event, and how are they doing?" Each row is **one wallet's position across an entire event** — what they put in, what it's worth, and their PnL — with the individual outcomes they hold nested inside the row. That nesting is what lets a client render a collapsed leaderboard and expand any trader to reveal the outcomes behind their number, without a second request. ![Holders leaderboard ranked by total PnL, with a trader row expanded into per-outcome invested, PnL and ROI](https://mintcdn.com/datadash/hVPzDAnHH86-Xa05/images/holders.png?fit=max\&auto=format\&n=hVPzDAnHH86-Xa05\&q=85\&s=1cdc0e4265ed86f7a89b3290541a4185) One wallet expanded to show the six outcomes behind its event-level total. ## Three views | Endpoint | Returns | | - | - | | `POST /api/v1/market-holders/all` | Every position, open and closed. | | `POST /api/v1/market-holders/active` | Only currently-held positions. | | `POST /api/v1/market-holders/closed` | Only exited positions. | They share a shape, but not every column appears on all three — `currentValue` is absent from `closed`, since an exited position has none. The table below marks where each column applies. ## Columns | Column | Meaning | | - | - | | **`user`** | The wallet. | | **`outcomes`** | How many distinct outcomes this wallet holds in the event. | | **`invested`** | Total USD put in. | | **`currentValue`** | Current market value of what's still held. *(all, active)* | | **`totalPnl`** | Realized plus unrealized PnL, in USD. | | **`unrealizedPnl`** | PnL on positions still open. *(all only)* | | **`pnlPercentage`** | Return on investment, as a percentage. | | **`volume`** | Total traded volume. *(all, closed)* | | **`tokenMetadata`** | The per-outcome breakdown — see below. | ## Outcome-level detail `tokenMetadata` is an array, one entry per outcome the wallet holds: | Field | Meaning | | - | - | | `tokenName` | The outcome's name. | | `isYesToken` | Whether this is the Yes side. | | `avgBuyingPrice` | Average entry price. | | `total_bought_shares` | Shares acquired. | | `invested` | USD put into this outcome. | | `totalPnl` | PnL on this outcome. | | `unrealizedPnl` | PnL on the part still held. *(all, active)* | | `pnlPercentage` | ROI on this outcome. | | `volume` | Traded volume on this outcome. | | `marketId` | The market this outcome belongs to. | | `marketClosed` | Whether that market has closed. | > [!WARNING] > > Every value inside `tokenMetadata` is a **string**, including the numeric and boolean ones — `"invested": "30740.5"`, `"isYesToken": "true"`. Parse them before use. The top-level columns are properly typed; only this nested payload is string-encoded. ## Scoping the query Holders is always scoped to an event, so **`eventId` is required**. ```json theme={null} { "page": { "limit": 50 }, "filter": [ { "field": "eventId", "operator": "eq", "value": 1234 } ], "orderBy": [{ "field": "totalPnl", "direction": "desc" }] } ``` Omitting it returns `400`. ## Narrowing further Beyond `eventId`, you can filter on `userId`, `positionId`, `userRank`, and the numeric measures — `invested`, `totalPnl`, `unrealizedPnl`, `pnlPercentage`, `currentValue` and `volume`. See [Filtering](/filters) for the syntax. Whales with a losing position, for example: ```json theme={null} { "page": { "limit": 50 }, "filter": [ { "field": "eventId", "operator": "eq", "value": 1234 }, { "field": "invested", "operator": "gte", "value": 100000 }, { "field": "totalPnl", "operator": "lt", "value": 0 } ], "orderBy": [{ "field": "invested", "direction": "desc" }] } ``` Or restrict to a [cohort](/cohorts) of wallets you already track: ```json theme={null} { "page": { "limit": 50 }, "filter": [ { "field": "eventId", "operator": "eq", "value": 1234 }, { "field": "userId", "operator": "inCohort", "value": ["01HQ2K..."] } ] } ``` > [!NOTE] > > Holders has no `searchKey` — it's already scoped to one event, so there's nothing to search across. Use the [Activity](/activity) endpoint to find an event by name first. ## API endpoints > [card] [All Holders](/api-reference) > > `POST /api/v1/market-holders/all` > [card] [Active Holders](/api-reference) > > `POST /api/v1/market-holders/active` > [card] [Closed Holders](/api-reference) > > `POST /api/v1/market-holders/closed` # Datadash Analytics API Source: https://docs.datadash.xyz/index On-chain prediction-market intelligence: wallet performance, positions, holders, smart-money edge and insider signals. Datadash turns raw prediction-market activity into structured, query-ready analytics. Every endpoint returns a ranked, paginated list of rows you can sort and search, with no indexing and no on-chain parsing on your side. > [card] [API Reference](/api-reference) > > Full schema for every endpoint, request and response. > [card] [Dashboard](https://datadash.xyz) > > Explore the same data visually at datadash.xyz. > [card] [Follow updates](https://x.com/datadashxyz) > > Product news and changes on X. ## What you can query > [card] Activity > > Chronological log of every buy and sell fill, enriched with market, event, > category and series metadata. > [card] Positions > > Active, closed and all-time positions for a wallet or cohort: invested, > shares, ROI and realized/unrealized PnL. > [card] Holders > > User-level holders of active, closed or all market positions, with nested > token-level detail. > [card] Profiles > > Per-wallet performance: PnL, win rate, volume, ROI, hold time and trade > counts, overall or broken down by category. > [card] Smart Money > > Markets ranked by smart-money edge, plus Yes/No and neg-risk summaries and > per-wallet positions. > [card] Signals > > Per-wallet, per-position insider signal scores for currently-held legs in > active markets. ## How requests work Every endpoint is a `POST` that takes the same request shape: * **`page`**: required. `limit` (and optional `offset`) for pagination. * **`orderBy`**: optional. A prioritized list of `{ field, direction }` sort keys; the first is the primary sort. Falls back to the table's default ranking when omitted. * **`searchKey`**: optional, where supported. Free-text search over the endpoint's primary entity (market, event or wallet). Responses are a JSON array of rows. See the [API Reference](/api-reference) for the exact fields on each row. ## Beyond querying Generate a typed client from the same spec the reference is built from — see [Generating a Client](/openapi-clients) for TypeScript and Python. Or skip the code entirely: connect the [MCP server](/mcp-server) to Claude, Cursor or VS Code and ask questions of the data in plain English. # MCP Server Source: https://docs.datadash.xyz/mcp-server Query Datadash analytics and manage cohorts from Claude Code, the Claude app, Codex, Cursor, VS Code, Gemini CLI or any MCP client. Datadash runs a [Model Context Protocol](https://modelcontextprotocol.io) server alongside the REST API. Connect it to an AI assistant and you can ask questions in plain English — "which wallets are up the most on election markets this month?" — and the assistant composes the queries, runs them and reads the rows for you. ``` https://api.datadash.xyz/mcp ``` It uses the Streamable HTTP transport and authenticates with the same `X-Api-Key` header as the REST API. The [Datadash AI plugin](https://github.com/datadash-xyz/mcp-skills-plugin) bundles this server with skills, such as wallet analysis and smart money, that teach the assistant which tables answer which question and how to read the numbers. Where your tool supports it, installing the plugin is the quickest setup. > [!NOTE] > > The **MCP** option in this site's page menu connects an assistant to *these docs*, for searching them. The server on this page connects it to Datadash's *data*. ## Setup **1. Create an API key** Follow [API Keys](/api-keys) to create one. The assistant acts with that key's full access, including creating, changing and deleting your cohorts. Create a key just for your MCP client, so you can revoke it without affecting anything else. **2. Pick your AI tool** Each tab has the exact setup. Replace `` with the key from step 1. > [tab] Claude Code > > Install the Datadash AI plugin from inside Claude Code (v2.1.275 or later): > > ``` > /plugin install datadash --marketplace datadash-xyz/mcp-skills-plugin > ``` > > Confirm the marketplace, choose a scope, then enter your Datadash API key when prompted. > > To add only the server, without the plugin's skills, register it directly. `--scope user` makes it available in every project: > > ```bash theme={null} > claude mcp add --scope user --transport http datadash https://api.datadash.xyz/mcp --header "X-Api-Key: " > ``` > > Start a new session and open the MCP menu. **datadash** should be listed as connected: > > ```bash theme={null} > claude /mcp > ``` > [tab] Claude app > > Install the Datadash AI plugin in Claude on the web or desktop: > > 1. Open **Customize**, then **Plugins**. > 2. Select **Add marketplace** and enter `datadash-xyz/mcp-skills-plugin`. > 3. Install **Datadash** from it. > 4. Open the plugin's **Connectors** tab and connect Datadash. > [tab] Codex > > Install the Datadash AI plugin. Set your key in the environment Codex runs in, then add the marketplace: > > ```bash theme={null} > export DATADASH_API_KEY= > codex plugin marketplace add datadash-xyz/mcp-skills-plugin > ``` > > Then run `/plugins` inside Codex, select **Datadash** and install it. > > To add only the server, without the plugin's skills: `codex mcp add` can't set a custom header, so add the server to `~/.codex/config.toml` directly: > > ```toml ~/.codex/config.toml theme={null} > [mcp_servers.datadash] > url = "https://api.datadash.xyz/mcp" > http_headers = { "X-Api-Key" = "" } > ``` > > To keep the key out of the file, use `env_http_headers = { "X-Api-Key" = "DATADASH_API_KEY" }` instead and export `DATADASH_API_KEY` in your shell. > > Check that **datadash** is listed as enabled: > > ```bash theme={null} > codex mcp list > ``` > [tab] Cursor > > Add the server to `~/.cursor/mcp.json`, or `.cursor/mcp.json` to limit it to one project: > > ```json mcp.json theme={null} > { > "mcpServers": { > "datadash": { > "url": "https://api.datadash.xyz/mcp", > "headers": { > "X-Api-Key": "" > } > } > } > } > ``` > > Open **Cursor Settings** and find **datadash** in the MCP section. A green dot means it's connected. > [tab] VS Code > > Add the server to `.vscode/mcp.json` in your workspace. The `inputs` entry has VS Code prompt for the key once and store it, so it never sits in the file: > > ```json .vscode/mcp.json theme={null} > { > "inputs": [ > { > "type": "promptString", > "id": "datadash-api-key", > "description": "Datadash API key", > "password": true > } > ], > "servers": { > "datadash": { > "type": "http", > "url": "https://api.datadash.xyz/mcp", > "headers": { > "X-Api-Key": "${input:datadash-api-key}" > } > } > } > } > ``` > > Select **Start** above the `datadash` entry and enter your key when prompted. The tools are then available in Chat's agent mode. > [tab] Gemini CLI > > Install the Datadash AI plugin as a Gemini CLI extension: > > ```bash theme={null} > gemini extensions install https://github.com/datadash-xyz/mcp-skills-plugin > ``` > > Enter your Datadash API key when prompted. It is stored as `DATADASH_API_KEY`. > [tab] Other > > Any client that speaks Streamable HTTP and can send a custom header will work. Point it at `https://api.datadash.xyz/mcp` and send your key as `X-Api-Key`. > > The server is stateless: every request is authenticated on its own, and no session carries over between them. **3. You're set** Datadash is connected. Start a new chat and ask about the data. The prompts below are a good place to start. ## What you can ask Once connected, just ask. A few starting points: * *"Who are the top 10 wallets by realized PnL in crypto markets?"* * *"What is smart money positioned on in the biggest active politics markets?"* * *"Show me the open positions of 0xAb8D...90F1, largest first."* * *"Build a cohort of wallets with over \$100k in volume and a win rate above 60%, then tell me what they're holding."* The assistant works out the table, fields and filters itself. You don't need to know the request shape. When it creates or reports on a cohort, it links you to that cohort in the dashboard. ## Tools The server exposes a small, fixed set of tools. Rather than one tool per endpoint, a single `query_table` takes the table as an argument, and `get_schema` describes every table in one call. | Tool | What it does | | - | - | | `get_schema` | Every table, its fields, which are filterable and sortable, and a worked request example. Called once, before anything else. | | `query_table` | Run a query against one table: the same filter, `orderBy` and `page` body the REST endpoint takes. | | `query_lookup` | Find IDs by name — for example, the market IDs matching "presidential election" — to use in a `query_table` filter. | | `list_cohorts` | List your cohorts and their build status. | | `get_cohort` | Read a cohort's status, size and criteria. Can wait for a build to finish. | | `list_cohort_wallets` | Page through the wallet addresses in a cohort. | | `create_cohort` | Save a wallet segment defined by criteria over the tables. | | `update_cohort` | Rename a cohort or replace its criteria, which rebuilds it. | | `create_static_cohort` | Save a fixed list of wallet addresses as a cohort. | | `update_static_cohort` | Rename a static cohort or replace its wallet list. | | `delete_cohort` | Delete a cohort permanently. | The schema is also published as the resource `datadashxyz://schema`, for clients that can load resources into context without spending a tool call. ## Things worth knowing > [accordion] It's the REST API underneath > > A tool call runs through the same validation, filtering and authentication as the equivalent REST request. The [filter grammar](/filters), page limits and error messages are identical, so anything you can do over MCP you can reproduce with `curl`. That makes it a quick way to prototype a query before you write code. > [accordion] Results are paged > > The assistant picks a `page.limit` for each query. When a result fills the page, the tool says so, and the assistant can either narrow the filter or read on with `page.offset`. If an answer looks suspiciously round, ask whether it saw every row. > [accordion] Cohorts build in the background > > A criteria cohort's membership is computed asynchronously after it's created or changed. The assistant waits for the build to finish (up to two minutes) before reading its wallets. A static cohort is ready as soon as it's saved. See [Cohorts](/cohorts) for how criteria work. > [accordion] Names resolve to IDs > > Markets, events and similar entities are filtered by ID, not name. The assistant finds the IDs with `query_lookup` first. When a name matches several candidates, it should pick the right ones or ask you. If an answer covers the wrong market, name the market more precisely. ## Next steps > [card] [API Keys](/api-keys) > > Create a dedicated key for your MCP client. > [card] [Cohorts](/cohorts) > > How cohort criteria are defined and built. # Generating a Client Source: https://docs.datadash.xyz/openapi-clients Build a typed TypeScript or Python client from the Datadash OpenAPI spec. The [API Reference](/api-reference) is generated from an OpenAPI 3.0 document, and so is every code sample on it. That same document is what you point a generator at, so your client's types stay in step with the API instead of drifting from a hand-written wrapper. ``` https://docs.datadash.xyz/openapi.json ``` Both generators below take that URL directly. Point them at a local copy instead if you want the spec pinned in your repo — regenerating then becomes a reviewable diff. ## TypeScript [`@hey-api/openapi-ts`](https://heyapi.dev) emits typed request functions plus the models behind them. Install it and the fetch client: ```bash theme={null} pnpm add -D @hey-api/openapi-ts pnpm add @hey-api/client-fetch ``` Configure it at the root of your project: ```ts openapi-ts.config.ts theme={null} import { defineConfig } from "@hey-api/openapi-ts"; export default defineConfig({ input: "https://docs.datadash.xyz/openapi.json", output: "src/datadash", plugins: ["@hey-api/client-fetch"], }); ``` ```bash theme={null} pnpm exec openapi-ts ``` Each operation becomes a function named after its `operationId` — `listPositionsActive`, `listActivity`, `listSmartMoneyGlobal`, and so on. Set the base URL and your [API key](/api-keys) once: ```ts theme={null} import { client, listPositionsActive } from "./datadash"; client.setConfig({ baseUrl: "https://api.datadash.xyz", headers: { "X-Api-Key": process.env.DATADASH_API_KEY! }, }); const { data, error } = await listPositionsActive({ body: { page: { limit: 50 }, filter: [ { field: "userId", operator: "eq", value: "0xAb8D...90F1" }, { field: "value", operator: "gte", value: 1000 }, ], }, }); if (error) throw new Error(error.message); data?.forEach((row) => console.log(row.token?.marketQuestion, row.unrealizedPnl), ); ``` > [!TIP] > > Prefer something smaller? [`openapi-typescript`](https://openapi-ts.dev) > generates types only — no runtime — and pairs with `openapi-fetch` for the > calls. Good when you already have a fetch wrapper you like. ## Python [`openapi-python-client`](https://github.com/openapi-generators/openapi-python-client) generates an `httpx`-based package with `attrs` models and full type hints. By default the package is named after the spec title, which gives you `data_dash_analytics_api_client`. Override it: ```yaml openapi-python-client.yaml theme={null} project_name_override: datadash-client package_name_override: datadash_client ``` ```bash theme={null} pipx run openapi-python-client generate \ --url https://docs.datadash.xyz/openapi.json \ --config openapi-python-client.yaml ``` Use `AuthenticatedClient` for the `X-Api-Key` header. It defaults to `Authorization: Bearer`, so set the header name and clear the prefix: ```python theme={null} import os from datadash_client import AuthenticatedClient from datadash_client.api.positions import list_positions_active from datadash_client.models import PageInput client = AuthenticatedClient( base_url="https://api.datadash.xyz", token=os.environ["DATADASH_API_KEY"], auth_header_name="X-Api-Key", prefix="", ) rows = list_positions_active.sync( client=client, body={ "page": {"limit": 50}, "filter": [ {"field": "userId", "operator": "eq", "value": "0xAb8D...90F1"}, {"field": "value", "operator": "gte", "value": 1000}, ], }, ) for row in rows: print(row.token.market_question, row.unrealized_pnl) ``` Operations live under `datadash_client.api.`, where the tag is the section it appears under in the reference — `positions`, `activity`, `holders`, `profiles`, `signals`, `smart_money`, `cohorts`. Each exposes `sync`, `sync_detailed`, `asyncio` and `asyncio_detailed`. ## Things worth knowing before you generate > [accordion] List endpoints return a bare array > > Responses are a root-level JSON array of rows, not an envelope. Generated return types are `Row[]` / `list[Row]` — there is no `data` or `results` field to unwrap. Pagination is driven entirely by the `page` you send. > [accordion] Big integers arrive as strings > > `tokenId` is declared as `type: string` with `format: big-integer`. That > format is not one OpenAPI defines, so generators fall back to plain strings — > which is what you want, since a 256-bit value can't round-trip through a JSON > number. Parse it with `BigInt` or `int()` if you need arithmetic. See > [Position IDs](/position-ids) for the 32-bit alternative. > [accordion] Filters are discriminated by field type > > Each endpoint's filter is a union of condition shapes — numeric, text, ID, > boolean, time — so the operators a generated type accepts depend on the field. > If your generator flattens the union awkwardly, build the filter as a plain > object literal and let the request type check the outer shape. > [Filtering](/filters) documents the full grammar. ## Next steps > [card] [API Keys](/api-keys) > > Authenticate your generated client. > [card] [Filtering](/filters) > > The condition and group grammar every list endpoint accepts. # Position IDs Source: https://docs.datadash.xyz/position-ids The 32-bit identifier for a single market outcome, and how it relates to market IDs and CLOB token IDs. A **position** is one side of one market — the Yes token or the No token. `positionId` is the 32-bit integer Datadash uses to name it. It's the join key behind activity rows, positions, holders and signals, and it's the value every `positionId` filter expects. ## How it's built Polymarket identifies each outcome by its CLOB token ID, a 256-bit integer. Datadash derives a compact `uint32` from the market and the side instead: ``` positionId = (marketId << 1) | isYesToken ``` Every market has exactly two outcomes, so 31 bits of market ID (about 2.1 billion markets) plus 1 bit of side covers every token. The mapping is 1:1 with the CLOB token ID — a position ID names exactly one token, and vice versa. | `positionId` | `marketId` | Side | | - | - | - | | `2468` | `1234` | No | | `2469` | `1234` | Yes | | `2470` | `1235` | No | | `2471` | `1235` | Yes | ## Taking one apart The market ID is the high 31 bits, the side is the low bit, and flipping that low bit gives you the opposite outcome in the same market. ```ts TypeScript theme={null} const marketId = positionId >>> 1; const isYes = (positionId & 1) === 1; const complement = positionId ^ 1; // the other side of the same market ``` ```python Python theme={null} market_id = position_id >> 1 is_yes = position_id & 1 == 1 complement = position_id ^ 1 # the other side of the same market ``` Because the complement is a single XOR, "show me both legs of this market" needs no lookup: `positionId` and `positionId ^ 1` are the pair. ## Where it appears **In responses**, `positionId` is carried on the resolved `token` object, alongside the CLOB `tokenId` and the market and event it belongs to: ```json theme={null} { "token": { "positionId": 2469, "tokenId": "7147384807...4923", "tokenName": "Yes", "isYesToken": true, "marketId": 1234, "marketQuestion": "Will X win?", "eventId": 88 }, "tags": [ { "id": 7, "label": "Politics" }, { "id": 9, "label": "US" } ] } ``` `tokenId` is returned as a **string**, not a number — a 256-bit value does not survive JSON's double-precision numbers. `positionId` is a plain integer. **In filters**, `positionId` accepts `in` and `notIn`, with a single value or an array: ```json theme={null} "filter": [ { "field": "positionId", "operator": "in", "value": [2469, 2471] } ] ``` It's available on activity, all three positions endpoints, all three holders endpoints, user positions, and signal scores. See [Filtering](/filters) for operators and grouping. ## Choosing between the IDs | Use | When | | - | - | | `positionId` | Filtering, joining and grouping inside Datadash. This is the default. | | `marketId` | You want both outcomes of a market at once. | | `tokenId` | You're reconciling against Polymarket's own CLOB API, which only knows token IDs. | # Signals Source: https://docs.datadash.xyz/signals Highest-conviction predictions across all markets. Signals surfaces the highest-conviction, currently-held bets across active markets. Every row is a single wallet's position in one market, scored so the strongest conviction rises to the top. ![Signals table listing trader, prediction, score, slippage, relative size, trade size and days left](https://mintcdn.com/datadash/hVPzDAnHH86-Xa05/images/signals.png?fit=max\&auto=format\&n=hVPzDAnHH86-Xa05\&q=85\&s=2fbafc300e286d9fe743acdad7c0846a) Held positions ranked by signal score, highest conviction first. ## Signal score Each position gets a **Score** from 0 to 100. Most of it comes from how the trader ranks by profit in the market's categories over the past year, with a bonus when the bet is big for them. It goes down when the price has moved away from their entry, or when they hold both sides of the market. > [card] [How the Signal score works](https://datadash.xyz/blog/polymarket-signal-score) > > Who gets scored, what goes into the score and how to read it, with a worked example. ## Columns | Column | Meaning | | - | - | | **Trader** | The wallet holding the position, with its rank. | | **Prediction** | The market, the outcome held (Yes/No and price), and the number of shares. | | **Score** | Signal score from 0 to 100. Higher means stronger conviction. | | **Slippage** | Entry price slippage. A lower value means better pricing. | | **Rel. Size** | Trade size relative to the trader's typical position size. | | **Trade Size** | The most the trader has had in this position, in USD. | | **Days Left** | Whole days until the market resolves. | ## Filtering Filter signals by category (Politics, Sports, Esports, Crypto, Finance, Culture, Weather, Economics, Tech, and more) or search by market. Pair Signals with a [cohort](/cohorts) to focus only on the wallets you trust. ## API endpoints > [card] [Signal Scores](/api-reference) > > `POST /api/v1/signals/scores`: per-wallet, per-position insider scores for held legs in active markets. > [card] [Signal Tag Counts](/api-reference) > > `POST /api/v1/signals/tag-counts`: signal counts grouped by category tag. # Smart Money Source: https://docs.datadash.xyz/smart-money Where the top wallets are positioned across every market. Smart Money ranks markets by the gap between where a cohort of top wallets is positioned and the live market price. It surfaces the markets where the sharpest traders most disagree with the crowd, so you can see conviction before it shows up in the odds. > [card] [How Smart Money works](https://datadash.xyz/blog/polymarket-smart-money) > > What counts as smart money, how wallets turn into odds and Edge, and when smart money gets it wrong, with a worked example. ## The global view The main table lists every market the selected cohort holds, ranked by edge. Each row shows the cohort's implied outcome and price next to the live market price (for example, `Yes 2.8¢ vs smart money 100¢`). | Column | Meaning | | - | - | | **Edge** | Distance between the smart-money implied Yes probability and the live Yes price. Larger edge means a wider disagreement. | | **At Risk** | Total USD the selected wallets hold in this market. | | **Liquidity** | The market's on-book liquidity. | | **Wallets** | Distinct wallets from the selected set holding this market. | | **Days Left** | Whole days until the market's end date. | Use the cohort selector (for example, **Top 1,000**) to change which wallet set defines "smart money". Any [cohort](/cohorts) can be used here, including your own. ## The market view Open a market to see how the cohort is split across outcomes. A Yes/No bar compares **Smart Money Odds** (the cohort's value-weighted probability) against **Market Odds** (the live price), and each side lists the individual wallets with their average entry price, amount **At Risk**, and open **Profit**. ![Smart Money market view with a Yes/No split bar and per-wallet at-risk and profit columns for each side](https://mintcdn.com/datadash/hVPzDAnHH86-Xa05/images/smart-money.png?fit=max\&auto=format\&n=hVPzDAnHH86-Xa05\&q=85\&s=53bf3dd79308dc80810b9a6979ce7b2f) The market view for a Top 1,000 cohort: smart-money odds against the live price, with the wallets on each side. Multi-outcome (neg-risk) events are handled separately, canonicalizing each wallet's true bet across the event's outcomes so the Yes and No sides stay comparable. ## API endpoints > [card] [Global Smart Money](/api-reference) > > `POST /api/v1/smart-money/global`: markets ranked by edge across the selected wallets. > [card] [Smart Money Summary](/api-reference) > > `POST /api/v1/smart-money/summary`: the Yes/No summary of an event, one row per open market, for binary and multi-outcome events alike. > [card] [Smart Money Holders](/api-reference) > > `POST /api/v1/smart-money/holders`: the wallets holding one side of one market within an event.