REST API / Polymarket / Smart Activity Markets

Smart Activity Markets (Polymarket)

Discover markets where profitable wallets are active. Ranks Polymarket markets by recent whale-sized trading from smart-money wallets (those with a strong lifetime PnL track record), with net buy/sell pressure per market. Cost-basis PnL/ROI fields are not yet computed and are returned as null.

GET/v2/polymarket/markets/smart-activity

Query Parameters

windowstring

Optional. 1d (default), 7d, 30d, or all_time. Longer windows favor recently-active wallets.

sort_bystring

Optional. smart_volume (default), smart_wallet_count, smart_trade_count, or last_active.

orderstring

Optional. desc (default) or asc.

statusstring

Optional. Filter by market status: open or closed.

min_smart_walletsinteger

Optional. Only markets with at least this many distinct smart wallets. Default 1.

limitinteger

Optional. Page size, 1–100, default 50.

offsetinteger

Optional. Pagination offset, default 0.

Response Schema

smart_wallet_criteriaobject

The thresholds defining a smart-money wallet for this response.

min_lifetime_pnl_usdnumber

Minimum lifetime PnL (USD) for a wallet to count as smart money.

min_trade_notional_usdnumber

Minimum per-fill notional (USD) for a trade to be counted.

windowstring

The rolling window applied (1d, 7d, 30d, or all_time).

marketsarray

Markets ranked by smart-money activity in the window.

condition_idstring

Market condition ID.

titlestring

Market title (null if not resolved).

market_slugstring

Market slug for URL construction (null if not resolved).

statusstring

Market status (e.g. open, closed).

smart_wallet_countinteger

Distinct smart-money wallets active in this market.

smart_volumenumber

Total whale-sized notional (USD) from smart wallets.

smart_trade_countinteger

Number of smart-money fills.

net_buyers_pctnumber

Fraction of smart wallets net-buying (buy volume > sell volume), 0–1.

avg_smart_lifetime_pnlnumber

Mean lifetime PnL (USD) across the active smart wallets.

last_active_tsinteger

Unix timestamp of the most recent smart-money fill in this market.

smart_realized_pnlnumber

Realized PnL from smart wallets. Not yet computed — returned as null (see _meta.unavailable_fields).

smart_total_pnlnumber

Total PnL from smart wallets. Not yet computed — returned as null.

avg_smart_roinumber

Average ROI across smart wallets. Not yet computed — returned as null.

avg_smart_win_ratenumber

Average win rate across smart wallets. Not yet computed — returned as null.

paginationobject

Offset-based pagination over the ranked list.

limitinteger

Requested page size.

offsetinteger

Page offset.

countinteger

Markets returned in this page.

totalinteger

Total markets matching the filters.

has_moreboolean

True when more markets exist beyond this page.

_metaobject

Source, data floor, and field-availability metadata.

sourcestring

Data source identifier.

data_available_fromstring

ISO timestamp; trade data is served from this point onward.

unavailable_fieldsarray

Fields returned as null because they require per-wallet cost-basis accounting not yet computed.

notestring

Which fields are exact vs. not yet available.

coverage_notestring

How smart-wallet coverage relates to the chosen window.

Error Responses

All errors return the same envelope. The code field is stable and programmatically branchable; error and message are human-readable. errors[] is present only on validation failures with field-level detail. See the full error code reference →

successboolean

Always `false` on error responses.

errorstring

Short, human-readable title (e.g. 'Invalid API Key.').

messagestring

Human-readable explanation for the error. Safe to surface in UIs.

codestring

Stable, hierarchical machine-readable code (e.g. 'validation.invalid_enum'). Use for programmatic handling.

doc_urlstring

Link to this code's entry in the Error Reference.

errorsobject[]

Optional. Present only on validation failures with field-level detail.

fieldstring

Name of the offending parameter.

codestring

Field-level machine code.

messagestring

Human-readable explanation.

Authentication

API Key

To secure your requests, we strongly recommend passing your API key via the X-API-Key header. This prevents sensitive keys from being exposed in access logs or browser history.

Request HeaderX-API-Key: pmx_test_5e8f...

Rate Limits

API rate limits are enforced based on the tier associated with your API key. Limits are tracked on two dimensions: requests per second and requests per month. Each completed request counts toward the global monthly quota. Separate endpoint-group monthly limits (matched markets, arbitrage, EV) only advance when the response body has success: true.

Usage is returned on responses via headers such as:

Response Headers (global)X-RateLimit-Limit-Second: 10X-RateLimit-Remaining-Second: 9X-RateLimit-Limit-Month: 1000X-RateLimit-Remaining-Month: 842Example (endpoint-group, when applicable)X-RateLimit-Limit-Arb-Month: 500X-RateLimit-Remaining-Arb-Month: 412

If you exceed a rate limit, the API returns a 429 status with a Retry-After header indicating when you can resume.

Request

Live API Key

Demo Mode

Verified

Parameters

Window

Response

—

Click EXECUTE to send a request →