Polymarket Data API: Trades, Positions and Wallet Activity

What is the Polymarket Data API?

The Data API is Polymarket's analytics and account-activity service at https://data-api.polymarket.com. It is separate from the Gamma API used for market discovery and the CLOB API used for live books and trading.

Polymarket's current Data API migration guide says new integrations should start on v2. Version 2 replaces several unrelated response shapes with a shared envelope, changes response fields from camelCase to snake_case and replaces offset pagination with opaque cursors.

What changed in Data API v2?

A cursor carries the seek position and page size. Some routes also bind sort settings into it. Follow the returned token instead of constructing one or reverting to offset arithmetic.

How do you fetch Polymarket trades?

The current endpoint is GET https://data-api.polymarket.com/v2/trades. Without a user it can serve a broader feed. Add user for one wallet, condition for up to 20 condition ids, or event_id for events.

curl -s \
  "https://data-api.polymarket.com/v2/trades?user=0xYOUR_ACCOUNT_WALLET&limit=100"

Trade rows include fields such as condition_id, token_id, proxy_wallet, side, price, size, timestamp and transaction hash. The route defaults taker_only to true, which serves each fill once on its taker side. Set it to false only when maker rows are part of the analysis.

{
  "data": [
    {
      "condition_id": "0x...",
      "token_id": "123...",
      "proxy_wallet": "0x...",
      "side": "BUY",
      "price": 0.61,
      "size": 40,
      "timestamp": 1789693200,
      "transaction_hash": "0x..."
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "opaque-token"
  }
}

The official v2 trades reference also documents an important retention distinction: user-shaped requests accept explicit time bounds, while condition and event shapes use their documented fixed window and the bare feed uses a rolling window.

How do you fetch current and closed positions?

The unified route is GET /v2/positions. It requires at least one anchor:

• user for positions owned by one account wallet.
• condition for holders of one market.
• Both values to narrow one wallet to one or more conditions.

# Open positions for one wallet
curl -s \
  "https://data-api.polymarket.com/v2/positions?user=0xYOUR_ACCOUNT_WALLET&status=OPEN&limit=100"

# Redeemable positions
curl -s \
  "https://data-api.polymarket.com/v2/positions?user=0xYOUR_ACCOUNT_WALLET&status=REDEEMABLE&limit=100"

# Closed positions
curl -s \
  "https://data-api.polymarket.com/v2/positions?user=0xYOUR_ACCOUNT_WALLET&status=CLOSED&limit=100"

OPEN is the default and includes settled winners that still hold redeemable tokens. REDEEMABLE narrows that subset. Position rows can include current size, average price, current value, realized and unrealized PnL, redeemable and mergeable flags, market metadata and the token id. See Polymarket's current positions contract for the full schema.

Which wallet address should you query?

Use the address that owns the Polymarket account's positions. It may not be the external signer address. Current Polymarket accounts use a Deposit Wallet, while older accounts may use a Proxy Wallet or Safe Wallet. Copying an EOA signer into a Data API query can return an empty list even when the associated account wallet holds positions. On-chain indexers are the other route to this data, compared in Predictefy vs Bitquery.

This is a data-identity issue, not an API failure. Keep these concepts separate:

How do you fetch complete wallet activity?

GET /v2/activity is broader than the trades route. It is user-anchored and can return trades, splits, merges, redemptions and other documented activity types.

curl -s \
  "https://data-api.polymarket.com/v2/activity?user=0xYOUR_ACCOUNT_WALLET&limit=100"

Filter with type, condition, event_id, side and an epoch-second time window. The default order is newest first. The activity reference documents keyset ordering and notes that a returned cursor binds the direction under which it was created.

Use activity when the question is "what changed in this wallet?" Use trades when the question is "which fills happened?" A split, merge or redeem changes token inventory but is not a trade, so a trade-only ledger cannot fully reconcile a wallet.

How do you paginate safely?

async function collectPages(firstUrl) {
  const rows = [];
  let url = new URL(firstUrl);

  while (url) {
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error('Polymarket Data API returned ' + response.status);
    }

    const page = await response.json();
    rows.push(...page.data);

    const cursor = page.pagination?.next_cursor;
    if (!cursor) break;

    const next = new URL(firstUrl);
    next.searchParams.set('cursor', cursor);
    url = next;
  }

  return rows;
}

How does Predictefy expose Polymarket trades?

Predictefy has two deliberately different trade surfaces:

import Predictefy from '@predictefy/sdk';

const client = new Predictefy({
  apiKey: process.env.PREDICTEFY_API_KEY,
});

const outcomeTape = await client.polymarket.fetchTrades({
  outcomeId: process.env.POLYMARKET_OUTCOME_ID,
});

const walletTape = await client.polymarket.fetchWalletTrades(
  process.env.POLYMARKET_ACCOUNT_WALLET,
  { limit: 50 },
);

console.log({
  outcomeTrades: outcomeTape.length,
  walletTrades: walletTape.length,
  nextCursor: walletTape.nextCursor,
  asOf: walletTape.meta?.asOf,
  provenance: walletTape.meta?.provenance,
});

The normalized wallet rows expose venue, market and outcome ids, trade id, timestamp, wallet, side, price, amount and USD size where the source can prove them. Nullable values remain null rather than being guessed. Predictefy's Trader Intelligence reference states that unsupported wallet-history lanes return TRADERS_UNSUPPORTED instead of a fabricated empty history.

How do you read Polymarket positions through Predictefy?

Polymarket public positions are available through Predictefy's hosted account surface. Check capabilities first, then request the wallet's positions:

const capabilities = await client.account.fetchCapabilities({
  venue: 'polymarket',
});

if (!capabilities.positions.served) {
  throw new Error('Polymarket positions are not served');
}

const positions = await client.account.fetchPositions({
  venue: 'polymarket',
  accountId: process.env.POLYMARKET_ACCOUNT_WALLET,
  limit: 100,
});

for (const position of positions) {
  console.log({
    marketId: position.marketId,
    outcomeId: position.outcomeId,
    side: position.side,
    size: position.size,
    markPrice: position.markPrice,
    unrealizedPnl: position.unrealizedPnl,
    asOf: position.asOf,
  });
}

console.log({
  nextCursor: positions.nextCursor,
  asOf: positions.meta?.asOf,
  provenance: positions.meta?.provenance,
});

The REST equivalent is:

curl -s \
  "https://data.predictefy.com/v1/accounts/polymarket/ACCOUNT_WALLET/positions?limit=100" \
  -H "Authorization: Bearer $PREDICTEFY_API_KEY"

The normalized row distinguishes venue marketId from canonicalMarketId, preserves the outcome and includes explicit provenance. Predictefy's portfolio guide warns that an unsupported resource is not the same as an empty account. Render unavailable as unavailable, not as zero positions.

When should you use Predictefy alongside the Data API?

Use Predictefy when the application needs one market, trade, wallet-intelligence or position model that holds across several venues, so the same code reaches Polymarket and the other fifteen without a branch per venue. Reach for Polymarket's Data API directly when you want the native Polymarket detail, including the full activity taxonomy of token splits, merges and redemptions.

Most production systems run both, and the split falls out cleanly by task:

What should you not infer from public wallet data?

• A wallet address does not prove a person's identity.
• A visible position does not disclose an off-platform hedge.
• A trade timestamp does not prove the trader's information source or intent.
• Historical profit does not make the next trade a recommendation.
• An empty response can mean no rows, a wrong account address or a filter mismatch. Check the contract before drawing a conclusion.

Preserve the raw identifiers, query window, cursor chain and retrieval time when using these feeds in research. That makes the result reproducible and prevents a later snapshot from being presented as the data originally observed.

Frequently Asked Questions