Polymarket Data API v2 Migration Guide

Polymarket is retiring its original Data API v1 routes on October 24, 2026, making the move to Data API v2 a required upgrade for bots, analytics dashboards, portfolio trackers, market scanners, AI agents, and other applications still depending on the legacy endpoints.

The migration is more than adding /v2 to an existing URL.

Polymarket Data API v2 introduces a shared response contract, cursor-based pagination, snake_case response fields, unified position lifecycle handling, standardized condition identifiers, new portfolio and analytics endpoints, and updated official SDK behavior. At the same time, one important legacy endpoint—GET /v1/accounting/snapshot—remains on v1 and is not part of the October 24 retirement.

For automated traders, there is another important distinction: the Data API is only one part of a production Polymarket stack. A serious bot may use Data API v2 for portfolio, trade, PnL, activity, token and market-state reads while relying on WebSockets for real-time updates and the CLOB trading interface for order placement and cancellation.

That means the migration should not be treated as an isolated API refactor. It is a good opportunity to review the entire architecture:

Data API v2 → market/account state → strategy → deterministic risk checks → CLOB execution → order monitoring → reconciliation → database → alerts

For bots designed to operate continuously, the migration is also a good time to review VPS uptime, server region, geoblock checks, WebSocket reliability and deployment procedures.

What Changes From Polymarket Data API v1 to v2?

The first major improvement is consistency.

Data API v1 endpoints could return bare arrays or individual objects. In v2, responses use a shared envelope where the payload is placed under data, and paginated routes also return a pagination object. A normal missing result is represented as data: null or an empty list rather than automatically becoming an HTTP error.

A simplified v2 response now follows this pattern:

{
  "data": [
    {
      "proxy_wallet": "0x...",
      "condition_id": "0x...",
      "token_id": "...",
      "outcome": "Yes",
      "status": "OPEN"
    }
  ],
  "pagination": {
    "next_cursor": "..."
  }
}

That means old application logic such as:

const positions = await response.json();

for (const position of positions) {
  // process position
}

needs to become conceptually:

const response = await fetch(url);
const body = await response.json();

for (const position of body.data ?? []) {
  // process position
}

This sounds small, but any bot that assumes the top-level result is an array can break immediately after switching URLs.

The second major change is field casing.

v1 commonly returned fields such as:

proxyWallet
conditionId

v2 responses use:

proxy_wallet
condition_id

Polymarket still accepts both snake_case and camelCase spellings for v2 request parameters, which can make the transition easier, but developers should update their response models, database mappings and serialization logic to the documented v2 shapes rather than relying on old v1 structures.

The Biggest Migration Change: Offset Pagination Becomes Cursors

Pagination is one of the areas most likely to affect production bots.

Data API v1 used limit and offset, with offset-based access stopping at 10,000 rows. Data API v2 uses opaque cursors instead. The application requests its first page, reads pagination.next_cursor, sends that cursor with the next request, and continues until next_cursor becomes null.

The old pattern may look like:

/trades?user=0x...&limit=100&offset=0
/trades?user=0x...&limit=100&offset=100
/trades?user=0x...&limit=100&offset=200

The new approach becomes:

/v2/trades?user=0x...&limit=100

then:

/v2/trades?user=0x...&cursor=<next_cursor>

This is particularly useful for continuously changing datasets such as trade and activity feeds because the client no longer needs to calculate offsets while new rows are being added.

There are still rules developers need to understand. On feed routes such as /v2/trades and /v2/activity, the same filters should be resent on every page. Changing filters while following a cursor can effectively change the meaning of the pagination walk. Some other endpoints bind query values directly into the cursor and can reject contradictory parameters with a 400.

A robust generic pagination loop therefore looks more like:

cursor = None

while True:
    params = {
        "user": wallet,
        "limit": 100
    }

    if cursor:
        params["cursor"] = cursor

    response = requests.get(
        "https://data-api.polymarket.com/v2/trades",
        params=params,
        timeout=10
    )
    response.raise_for_status()

    payload = response.json()

    for trade in payload.get("data", []):
        process_trade(trade)

    cursor = payload.get("pagination", {}).get("next_cursor")

    if cursor is None:
        break

Production applications should also handle 429 responses and respect the returned Retry-After value instead of immediately retrying in a tight loop.

Position Handling Is Now Much Cleaner

Position handling receives one of the most useful redesigns.

Under v1, applications could use separate routes for current positions, closed positions and market-specific positions. Data API v2 consolidates those workflows into:

GET /v2/positions

and lets the client select the desired lifecycle state through a status filter. Current documented states include:

• OPEN
• REDEEMABLE
• REDEEMABLE_LOST
• MERGEABLE
• CLOSED

The response also includes redeemable and mergeable information so developers can model a wallet’s position lifecycle more consistently.

The migration therefore looks like:

Data API v1	Data API v2
/positions	/v2/positions
/closed-positions	/v2/positions?status=CLOSED
/v1/market-positions	/v2/positions?condition=...
/trades	/v2/trades
/activity	/v2/activity
/value	/v2/value
/traded	/v2/user-stats
/holders	/v2/holders
/oi	/v2/oi
/live-volume	/v2/live-volume
/v1/leaderboard	/v2/leaderboard

Market filtering changes as well.

v1 used the market parameter in several places. v2 standardizes filtering around condition, with aliases including condition_id and conditionId. Where lists are supported, Polymarket currently accepts up to 20 distinct comma-separated condition IDs.

If your bot stores Polymarket identifiers internally, this is a good time to stop treating every ID as interchangeable.

A cleaner internal data model should explicitly distinguish:

event ID

market ID

condition ID

token ID

Data API v2 uses each for a different purpose, and the /v2/tokens endpoint can help map tokens and conditions back to their associated markets and outcomes.

New v2 Endpoints Make the Data API More Useful for Bots and Analytics

The migration is not only about preserving old functionality.

Data API v2 adds several reads that make it easier to build analytics services and portfolio applications without recreating everything locally.

New endpoints include:

GET /v2/user-pnl
GET /v2/user-stats
GET /v2/user-volume
GET /v2/biggest-winners
GET /v2/prices-history
GET /v2/resolutions
GET /v2/tokens
GET /v2/status

The status endpoint is particularly useful for automated infrastructure because it provides a way to monitor data freshness rather than merely checking whether the HTTP server responds.

That difference matters.

A health check that only asks:

“Did the API return HTTP 200?”

is incomplete.

A production bot should also ask:

“Is the data current enough for this strategy to act on?”

The architecture can therefore track several separate health states:

Application process alive
↓
Data API reachable
↓
Data freshness acceptable
↓
WebSocket stream current
↓
CLOB execution reachable
↓
Wallet/account state reconciled

If the Data API is reachable but stale, the strategy may need to stop opening new positions rather than continuing with outdated information.

Another useful addition is /v2/prices-history. Polymarket’s current implementation uses several storage resolutions ranging from raw short-term data through increasingly coarser historical series. Developers requesting long windows should avoid assuming one-minute observations exist across the entire history; the API can select an appropriate available resolution when bucket_seconds is omitted.

Update the Official SDKs Before Updating Your Bot Logic

Developers using Polymarket’s official TypeScript or Python clients should also review their package versions.

Data API v2 support begins with version 0.10.0 of both the official TypeScript @polymarket/client package and Python polymarket-client. That release introduced breaking changes covering cursor-based trade/activity/position feeds, renamed market filters, time-window behavior and consolidated position methods.

For example, older SDK logic built around:

listClosedPositions(...)

needs to move toward the unified position API with a closed-position status.

Likewise, old market filters become condition-based filters, and trade/activity iteration now follows server cursors.

Do not simply update the dependency and deploy directly to production.

A safer process is:

freeze current production version → create migration branch → update SDK → fix compile/type errors → update response models → test pagination → compare v1 and v2 results → deploy canary instance → switch production reads

This becomes especially important because the latest SDK can contain changes unrelated to Data API migration. The purpose of the migration test is not merely to prove that the code runs; it is to prove that the new application produces the same intended trading state.

Do Not Migrate the Accounting Snapshot Endpoint

One exception needs to be handled deliberately.

Polymarket states that:

GET /v1/accounting/snapshot

has no v2 equivalent and is not included in the October 24 v1 retirement.

Therefore, a developer should not perform a global replacement such as:

/v1/ → /v2/

across the entire project.

Instead, create explicit route mappings.

For example:

positions          → v2
trades             → v2
activity           → v2
portfolio value    → v2
leaderboards       → v2
accounting snapshot → remain on existing v1 endpoint

Keeping API endpoints centralized in one module or configuration object makes this much easier than scattering hard-coded URLs throughout the strategy.

How Data API v2 Fits Into a 24/7 Polymarket Bot

A common architecture mistake is expecting the Data API to handle every part of the trading system.

It should not.

Data API v2 is excellent for reading wallet portfolios, positions, historical trades, activity, PnL, volume, token mappings, resolutions, holders, open interest and related analytics. Its read endpoints currently require no API key or authentication.

But real-time automated trading usually needs additional layers.

A production architecture can look like:

Data API v2 → portfolio/history/reference state

plus

WebSockets → continuous market and user updates

plus

CLOB trading API → signed order placement/cancellation

combined through:

Market Data → Strategy → Risk Engine → Execution → Order Monitor → Reconciliation → Database → Alerts

This is also where a VPS becomes relevant.

A browser does not need to stay open for an API-native bot, but some machine still needs to run the Python, TypeScript, Rust, database, WebSocket listener, risk engine and execution services.

If that machine is the trader’s home computer, power loss, sleep mode, ISP outages or accidental shutdown can stop the automation.

A persistent VPS removes the home computer from that runtime dependency.

For a deeper explanation of this infrastructure model, TradingVPS’s guide to Polymarket Geo Restrictions and 24/7 API Automation covers frontend-vs-API restrictions, geoblock checks, Dublin and Amsterdam hosting, WebSocket automation and persistent bot architecture.

VPS Location Matters—but It Must Never Be Used to Bypass Eligibility Rules

The Data API migration itself does not require moving servers.

However, developers rebuilding a bot for v2 should review where the rest of the trading infrastructure runs.

Polymarket’s current documentation states that its primary server infrastructure is in AWS eu-west-2, with eu-west-1 identified as the closest non-georestricted region. eu-west-1 corresponds to Ireland, which makes Dublin a logical region to benchmark for eligible API-native workloads.

TradingVPS also offers Dublin and Amsterdam environments designed for persistent Python, Node.js, WebSocket, database and trading-bot workloads. The practical reasons to evaluate these locations include stable connectivity, short network paths toward Polymarket’s European infrastructure, predictable compute resources, NVMe storage and a consistent dedicated IPv4 address.

For lightweight automation, a few fast CPU cores and roughly 4–8 GB of RAM may be enough. Larger systems combining multiple market workers, PostgreSQL or Redis, AI agents, historical data collection and several concurrent strategies may need more resources. Linux—particularly Ubuntu—is often the simplest environment for Python, Node.js, Docker and database-based API stacks, although Windows remains appropriate when the surrounding software requires it.

But server location and user eligibility are separate issues.

Polymarket instructs developers to check the requesting location before submitting orders. Its current geoblock endpoint returns whether the detected IP is blocked, along with country and region information. Orders from restricted API locations can be rejected.

A production bot should therefore perform a geoblock check:

at startup

after a VPS migration

after an IP change

and periodically as part of infrastructure health monitoring

If the environment becomes blocked, the execution layer should stop opening new positions instead of repeatedly retrying failed orders.

A VPS should be used to host activity the user or entity is already permitted to conduct—not to conceal residency, defeat KYC, evade sanctions or bypass jurisdictional restrictions.

That distinction is essential.

A Practical Migration Plan Before October 24

The safest approach is to run the migration as a controlled production change instead of waiting until the legacy endpoints disappear.

A practical sequence looks like this:

Step	Action
1	Inventory every v1 Data API endpoint in the project
2	Identify the exact v2 replacement
3	Leave /v1/accounting/snapshot unchanged
4	Update official SDKs to a v2-compatible release
5	Change response parsing to data / pagination
6	Convert response models from camelCase to snake_case
7	Replace offset loops with cursor iteration
8	Replace market filtering with condition where required
9	Consolidate position reads through /v2/positions
10	Add handling for data: null and empty lists
11	Add 429 / Retry-After handling
12	Add /v2/status to infrastructure monitoring
13	Run v1 and v2 in parallel and compare outputs
14	Test bot restart and pagination recovery
15	Deploy v2 before October 24, 2026

During parallel testing, compare more than simple row counts.

Verify:

position quantities

condition IDs

token IDs

realized and unrealized PnL

portfolio value

trade history

activity ordering

pagination completeness

closed and redeemable positions

database field mappings

One subtle schema change can produce a bot that looks healthy while its internal account state is wrong.

For an automated trading system, that is more dangerous than an obvious crash.

Production Safeguards Worth Adding During the Migration

API migrations are a good opportunity to remove assumptions from production code.

First, separate your data layer from your strategy layer.

The strategy should not care whether positions came from v1 or v2. It should receive a normalized internal position model from an API adapter.

Second, never treat null as zero automatically.

Polymarket’s v2 conventions state that missing or null numeric fields represent unavailable data rather than zero.

Third, implement rate-limit-aware retries.

If v2 returns 429, respect Retry-After, add bounded retries and avoid allowing every worker process to retry simultaneously.

Fourth, persist important synchronization markers. A process restart should not cause the bot to duplicate trades, reprocess an entire history incorrectly or assume that a truncated page means pagination has completed.

Finally, reconcile local state against venue state regularly.

A production bot should be able to compare:

local positions vs Data API positions

local fills vs trade history

local order state vs CLOB order state

local portfolio value vs venue value

If those states diverge beyond an expected tolerance, the safest response may be to stop generating new orders until reconciliation succeeds.

Frequently Asked Questions About Polymarket Data API v2

Final Thoughts: Treat the v2 Migration as an Infrastructure Upgrade, Not Just a URL Change

The move from Polymarket Data API v1 to v2 is a meaningful improvement for developers.

The new API provides a more consistent response contract, cursor-based pagination, unified position lifecycle handling, clearer identifiers, additional PnL and analytics endpoints, token lookup, resolution data and explicit data-freshness monitoring.

But those improvements require real code changes.

Applications need to handle the new data response envelope.

Pagination logic needs to move from offsets to cursors.

Response models need to move toward snake_case.

Market filters need to become condition-based.

Position code should consolidate around /v2/positions.

SDK users need to review breaking changes.

And production bots need to move before October 24, 2026 rather than discovering the dependency after v1 disappears.

The strongest migration also looks beyond the Data API itself.

A serious Polymarket trading system should clearly separate:

historical/account data

real-time market updates

strategy logic

risk controls

order execution

reconciliation

monitoring

infrastructure

Data API v2 can improve the first part of that architecture, but it does not replace WebSockets, CLOB execution or operational monitoring.

For 24/7 systems, the VPS remains the machine keeping those components alive when the developer’s laptop is offline. Dublin has a particularly strong documentation-based infrastructure case because Polymarket identifies AWS eu-west-1 as the closest non-georestricted region to its primary eu-west-2 infrastructure, while Amsterdam is another nearby option worth benchmarking for authorized API-native applications.

The correct migration strategy is therefore not:

“Change /positions to /v2/positions and hope nothing breaks.”

It is:

inventory → migrate → normalize → validate → monitor → reconcile → deploy before retirement.

Do that properly, and Data API v2 becomes more than a forced upgrade. It becomes an opportunity to make the Polymarket bot cleaner, easier to monitor and better prepared for continuous production operation.