Wallet Activity

Use a wallet address to understand an account’s current exposure and trace how its activity has changed over time.

Open Positions

Inspect a wallet’s current outcome exposure and unrealized performance.

TypeScript
Python
API

Call listPositions() on a PublicClient or SecureClient.

const address = "0x8ba1f109551bD432803012645Ac136ddd64DBA72";

const pages = client.listPositions({ user: address, pageSize: 1 });

for await (const page of pages) {
  // page.items: Position[]
}

Output: Position[]

type Position = {
  conditionId: CtfConditionId;
  wallet?: Address | null;
  tokenId?: TokenId | null;
  size?: DecimalString | null;
  avgPrice?: DecimalString | null;
  initialValue?: DecimalString | null;
  currentValue?: DecimalString | null;
  cashPnl?: DecimalString | null;
  percentPnl?: number | null;
  totalBought?: DecimalString | null;
  realizedPnl?: DecimalString | null;
  percentRealizedPnl?: number | null;
  curPrice?: DecimalString | null;
  redeemable?: boolean | null;
  mergeable?: boolean | null;
  title?: string | null;
  slug?: string | null;
  icon?: string | null;
  eventId?: string | null;
  eventSlug?: string | null;
  outcome?: string | null;
  outcomeIndex?: number | null;
  oppositeOutcome?: string | null;
  oppositeTokenId?: TokenId | null;
  endDate?: IsoCalendarDateString | null;
  negativeRisk?: boolean | null;
};

[
  {
    "conditionId": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
    "wallet": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
    "tokenId": "107505882767731489358349912513945399560393482969656700824895970500493757150417",
    "size": "125.5",
    "avgPrice": "0.42",
    "initialValue": "52.71",
    "currentValue": "61.50",
    "cashPnl": "8.79",
    "percentPnl": 16.68,
    "curPrice": "0.49",
    "title": "Will the US confirm that aliens exist before 2027?",
    "slug": "will-the-us-confirm-that-aliens-exist-before-2027",
    "eventSlug": "will-the-us-confirm-that-aliens-exist-before-2027",
    "outcome": "Yes",
    "outcomeIndex": 0,
    "redeemable": false,
    "mergeable": false
  }
]

Call list_positions() on an AsyncPublicClient or AsyncSecureClient. The synchronous PublicClient and SecureClient provide the same method.

address = "0x8ba1f109551bD432803012645Ac136ddd64DBA72"

pages = client.list_positions(user=address, page_size=1)

async for page in pages:
    ...  # page.items: tuple[Position, ...]

Output: tuple[Position, ...]

class Position:
    condition_id: CtfConditionId
    wallet: EvmAddress | None
    token_id: TokenId | None
    size: Decimal | None
    avg_price: Decimal | None
    initial_value: Decimal | None
    current_value: Decimal | None
    cash_pnl: Decimal | None
    percent_pnl: float | None
    total_bought: Decimal | None
    realized_pnl: Decimal | None
    percent_realized_pnl: float | None
    cur_price: Decimal | None
    redeemable: bool | None
    mergeable: bool | None
    title: str | None
    slug: str | None
    icon: str | None
    event_id: str | None
    event_slug: str | None
    outcome: str | None
    outcome_index: int | None
    opposite_outcome: str | None
    opposite_token_id: TokenId | None
    end_date: date | None
    negative_risk: bool | None

[
  {
    "condition_id": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
    "wallet": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
    "token_id": "107505882767731489358349912513945399560393482969656700824895970500493757150417",
    "size": "125.5",
    "avg_price": "0.42",
    "initial_value": "52.71",
    "current_value": "61.50",
    "cash_pnl": "8.79",
    "percent_pnl": 16.68,
    "cur_price": "0.49",
    "title": "Will the US confirm that aliens exist before 2027?",
    "slug": "will-the-us-confirm-that-aliens-exist-before-2027",
    "event_slug": "will-the-us-confirm-that-aliens-exist-before-2027",
    "outcome": "Yes",
    "outcome_index": 0,
    "redeemable": false,
    "mergeable": false
  }
]

List the open positions for a wallet:

ADDRESS="0x8ba1f109551bD432803012645Ac136ddd64DBA72"

curl "https://data-api.polymarket.com/positions?user=$ADDRESS&limit=1"

The response contains the wallet’s open positions:

Response

[
  {
    "proxyWallet": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
    "asset": "107505882767731489358349912513945399560393482969656700824895970500493757150417",
    "conditionId": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
    "size": 125.5,
    "avgPrice": 0.42,
    "initialValue": 52.71,
    "currentValue": 61.5,
    "cashPnl": 8.79,
    "percentPnl": 16.68,
    "curPrice": 0.49,
    "title": "Will the US confirm that aliens exist before 2027?",
    "slug": "will-the-us-confirm-that-aliens-exist-before-2027",
    "eventSlug": "will-the-us-confirm-that-aliens-exist-before-2027",
    "outcome": "Yes",
    "outcomeIndex": 0
  }
]

Closed Positions

Review the positions a wallet has exited or that have resolved, including their realized performance.

TypeScript
Python
API

Call listClosedPositions() on a PublicClient or SecureClient.

const pages = client.listClosedPositions({
  user: address,
  pageSize: 1,
});

for await (const page of pages) {
  // page.items: ClosedPosition[]
}

Output: ClosedPosition[]

type ClosedPosition = {
  wallet?: Address | null;
  tokenId?: TokenId | null;
  conditionId?: CtfConditionId | null;
  avgPrice?: DecimalString | null;
  totalBought?: DecimalString | null;
  realizedPnl?: DecimalString | null;
  curPrice?: DecimalString | null;
  timestamp?: EpochMilliseconds | null;
  title?: string | null;
  slug?: string | null;
  icon?: string | null;
  eventSlug?: string | null;
  outcome?: string | null;
  outcomeIndex?: number | null;
  oppositeOutcome?: string | null;
  oppositeTokenId?: TokenId | null;
  endDate?: MixedDateTimeString | null;
};

[
  {
    "wallet": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
    "tokenId": "7305630249804085635496399869905769372294302716159034447326228509068694952392",
    "conditionId": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
    "avgPrice": "0.58",
    "totalBought": "250.00",
    "realizedPnl": "34.25",
    "curPrice": "0.00",
    "timestamp": 1782752879000,
    "title": "Will the US confirm that aliens exist before 2027?",
    "slug": "will-the-us-confirm-that-aliens-exist-before-2027",
    "eventSlug": "will-the-us-confirm-that-aliens-exist-before-2027",
    "outcome": "No",
    "outcomeIndex": 1
  }
]

Call list_closed_positions() on an AsyncPublicClient or AsyncSecureClient. The synchronous PublicClient and SecureClient provide the same method.

pages = client.list_closed_positions(user=address, page_size=1)

async for page in pages:
    ...  # page.items: tuple[ClosedPosition, ...]

Output: tuple[ClosedPosition, ...]

class ClosedPosition:
    wallet: EvmAddress | None
    token_id: TokenId | None
    condition_id: CtfConditionId | None
    avg_price: Decimal | None
    total_bought: Decimal | None
    realized_pnl: Decimal | None
    cur_price: Decimal | None
    timestamp: datetime | None
    title: str | None
    slug: str | None
    icon: str | None
    event_slug: str | None
    outcome: str | None
    outcome_index: int | None
    opposite_outcome: str | None
    opposite_token_id: TokenId | None
    end_date: date | None

[
  {
    "wallet": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
    "token_id": "7305630249804085635496399869905769372294302716159034447326228509068694952392",
    "condition_id": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
    "avg_price": "0.58",
    "total_bought": "250.00",
    "realized_pnl": "34.25",
    "cur_price": "0.00",
    "timestamp": "2026-06-29T17:07:59Z",
    "title": "Will the US confirm that aliens exist before 2027?",
    "slug": "will-the-us-confirm-that-aliens-exist-before-2027",
    "event_slug": "will-the-us-confirm-that-aliens-exist-before-2027",
    "outcome": "No",
    "outcome_index": 1
  }
]

List the closed positions for a wallet:

curl "https://data-api.polymarket.com/closed-positions?user=$ADDRESS&limit=1"

The response contains the wallet’s closed positions:

Response

[
  {
    "proxyWallet": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
    "asset": "7305630249804085635496399869905769372294302716159034447326228509068694952392",
    "conditionId": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
    "avgPrice": 0.58,
    "totalBought": 250,
    "realizedPnl": 34.25,
    "curPrice": 0,
    "timestamp": 1782752879,
    "title": "Will the US confirm that aliens exist before 2027?",
    "slug": "will-the-us-confirm-that-aliens-exist-before-2027",
    "eventSlug": "will-the-us-confirm-that-aliens-exist-before-2027",
    "outcome": "No",
    "outcomeIndex": 1
  }
]

Activity History

Follow the timeline for a wallet across trades and other activity.

TypeScript
Python
API

Call listActivity() on a PublicClient or SecureClient.

const pages = client.listActivity({ user: address, pageSize: 1 });

for await (const page of pages) {
  // page.items: Activity[]
}

Activity is a discriminated union. The type field identifies each variant:

Output: Activity[]

type Activity =
  | TradeActivity
  | SplitActivity
  | MergeActivity
  | RedeemActivity
  | ConversionActivity
  | RewardActivity
  | MakerRebateActivity
  | ReferralRewardActivity
  | YieldActivity;

[
  {
    "type": "TRADE",
    "isCombo": false,
    "wallet": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
    "timestamp": 1782752879000,
    "transactionHash": "0x4f3d2c1b0a9876543210fedcba9876543210fedcba9876543210fedcba987654",
    "conditionId": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
    "tokenId": "107505882767731489358349912513945399560393482969656700824895970500493757150417",
    "side": "BUY",
    "shares": "25",
    "amount": "12.25",
    "price": "0.49",
    "title": "Will the US confirm that aliens exist before 2027?",
    "slug": "will-the-us-confirm-that-aliens-exist-before-2027",
    "eventSlug": "will-the-us-confirm-that-aliens-exist-before-2027",
    "outcome": "Yes",
    "outcomeIndex": 0
  },
  {
    "type": "REWARD",
    "wallet": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
    "timestamp": 1782752979000,
    "transactionHash": "0x7a6b5c4d3e2f109876543210fedcba9876543210fedcba9876543210fedcba98",
    "amount": "5"
  }
]

Call list_activity() on an AsyncPublicClient or AsyncSecureClient. The synchronous PublicClient and SecureClient provide the same method.

pages = client.list_activity(user=address, page_size=1)

async for page in pages:
    ...  # page.items: tuple[Activity, ...]

Activity is a union of the supported activity variants:

Output: tuple[Activity, ...]

Activity = (
    TradeActivity
    | ComboTradeActivity
    | SplitActivity
    | MergeActivity
    | RedeemActivity
    | ConversionActivity
    | RewardActivity
    | MakerRebateActivity
    | ReferralRewardActivity
    | YieldActivity
    | UnknownActivity
)

[
  {
    "type": "TRADE",
    "is_combo": false,
    "wallet": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
    "timestamp": "2026-06-29T17:07:59Z",
    "transaction_hash": "0x4f3d2c1b0a9876543210fedcba9876543210fedcba9876543210fedcba987654",
    "condition_id": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
    "token_id": "107505882767731489358349912513945399560393482969656700824895970500493757150417",
    "side": "BUY",
    "shares": "25",
    "amount": "12.25",
    "price": "0.49",
    "title": "Will the US confirm that aliens exist before 2027?",
    "slug": "will-the-us-confirm-that-aliens-exist-before-2027",
    "event_slug": "will-the-us-confirm-that-aliens-exist-before-2027",
    "outcome": "Yes",
    "outcome_index": 0
  }
]

List the activity for a wallet:

curl "https://data-api.polymarket.com/activity?user=$ADDRESS&limit=1"

The response contains the wallet’s activity:

Response

[
  {
    "proxyWallet": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
    "timestamp": 1782752879,
    "conditionId": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
    "type": "TRADE",
    "size": 25,
    "usdcSize": 12.25,
    "transactionHash": "0x4f3d2c1b0a9876543210fedcba9876543210fedcba9876543210fedcba987654",
    "price": 0.49,
    "asset": "107505882767731489358349912513945399560393482969656700824895970500493757150417",
    "side": "BUY",
    "title": "Will the US confirm that aliens exist before 2027?",
    "slug": "will-the-us-confirm-that-aliens-exist-before-2027",
    "eventSlug": "will-the-us-confirm-that-aliens-exist-before-2027",
    "outcome": "Yes",
    "outcomeIndex": 0
  }
]

Notifications

Notifications provide a short-lived record of unread events for the connected account. The CLOB retains them for 48 hours.

List Notifications

TypeScript
Python
API

Call fetchNotifications() on a SecureClient:

const notifications = await client.fetchNotifications();

// notifications: Notification[]

Output: Notification[]

type Notification = {
  id: NotificationId;
  owner: string;
  payload: unknown;
  timestamp: EpochMilliseconds;
  type: number;
};

[
  {
    "id": 1,
    "owner": "f4f247b7-4ac7-ff29-a152-04fda0a8755a",
    "type": 2,
    "payload": {
      "order_id": "0x72c66a1f70c00ac5e5eb9ce0452b7d118bc4869f8b822a1a8d8580c16e3ca83e"
    },
    "timestamp": 1675277676000
  }
]

Call get_notifications() on an AsyncSecureClient. The synchronous SecureClient provides the same method:

notifications = await client.get_notifications()

# notifications: tuple[Notification, ...]

Output: tuple[Notification, ...]

class Notification:
    id: int
    owner: str
    type: int
    payload: Any
    timestamp: datetime

[
  {
    "id": 1,
    "owner": "f4f247b7-4ac7-ff29-a152-04fda0a8755a",
    "type": 2,
    "payload": {
      "order_id": "0x72c66a1f70c00ac5e5eb9ce0452b7d118bc4869f8b822a1a8d8580c16e3ca83e"
    },
    "timestamp": "2023-02-01T18:54:36Z"
  }
]

List unread notifications for the account:

curl -G "https://clob.polymarket.com/notifications" \
  -H "POLY_ADDRESS: <signer_address>" \
  -H "POLY_SIGNATURE: <clob_l2_signature>" \
  -H "POLY_TIMESTAMP: <clob_request_timestamp>" \
  -H "POLY_API_KEY: <clob_api_key>" \
  -H "POLY_PASSPHRASE: <clob_api_passphrase>" \
  --data-urlencode "signature_type=<signature_type>"

Using the signer address and CLOB API credentials from API Authentication, create a fresh <clob_request_timestamp> and generate <clob_l2_signature> for GET /notifications. The signature_type query parameter is not part of the signed path:

message = <clob_request_timestamp> + "GET" + "/notifications"

clob_l2_signature = urlsafeBase64WithPadding(
  HMAC-SHA256(base64Decode(<clob_api_secret>), message)
)

Select signature_type from the connected account’s wallet type:

Wallet	`signature_type`
Deposit Wallet	`3`
Proxy Wallet	`1`
Safe Wallet	`2`
EOA	`0`

The response contains the unread notifications:

[
  {
    "id": 1,
    "owner": "f4f247b7-4ac7-ff29-a152-04fda0a8755a",
    "type": 2,
    "payload": {
      "order_id": "0x72c66a1f70c00ac5e5eb9ce0452b7d118bc4869f8b822a1a8d8580c16e3ca83e"
    },
    "timestamp": 1675277676
  }
]

Drop Notifications

Mark notifications as read after processing them. Dropped notifications no longer appear when you list unread notifications.

TypeScript
Python
API

Call dropNotifications() on a SecureClient with the notification IDs:

await client.dropNotifications({
  ids: notifications.map(({ id }) => String(id)),
});

Call drop_notifications() on an AsyncSecureClient. The synchronous SecureClient provides the same method:

await client.drop_notifications(
    ids=[notification.id for notification in notifications],
)

Send the notification IDs as a comma-separated list:

curl -X DELETE -G "https://clob.polymarket.com/notifications" \
  -H "POLY_ADDRESS: <signer_address>" \
  -H "POLY_SIGNATURE: <clob_l2_signature>" \
  -H "POLY_TIMESTAMP: <clob_request_timestamp>" \
  -H "POLY_API_KEY: <clob_api_key>" \
  -H "POLY_PASSPHRASE: <clob_api_passphrase>" \
  --data-urlencode "ids=1,2"

Using the signer address and CLOB API credentials from API Authentication, create a fresh <clob_request_timestamp> and generate <clob_l2_signature> for DELETE /notifications. The ids query parameter is not part of the signed path:

message = <clob_request_timestamp> + "DELETE" + "/notifications"

clob_l2_signature = urlsafeBase64WithPadding(
  HMAC-SHA256(base64Decode(<clob_api_secret>), message)
)

A successful request returns OK.

Portfolio Value

Read the current portfolio value for a wallet.

TypeScript
Python
API

Call fetchPortfolioValue() on a PublicClient or SecureClient.

const value = await client.fetchPortfolioValue({ user: address });

// value: Value[]

Output: Value[]

type Value = {
  user?: Address | null;
  value?: DecimalString | null;
};

[
  {
    "user": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
    "value": "1842.37"
  }
]

Call get_portfolio_values() on an AsyncPublicClient or AsyncSecureClient. The synchronous PublicClient and SecureClient provide the same method.

value = await client.get_portfolio_values(user=address)

# value: tuple[PortfolioValue, ...]

Output: tuple[PortfolioValue, ...]

class PortfolioValue:
    user: EvmAddress | None
    value: Decimal | None

[
  {
    "user": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
    "value": "1842.37"
  }
]

Fetch the portfolio value for a wallet:

curl "https://data-api.polymarket.com/value?user=$ADDRESS"

The response contains the wallet’s current portfolio value:

Response

[
  {
    "user": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
    "value": 1842.37
  }
]

Getting Started

Core Concepts

Market Data

Trading

Programs

Resources

Open Positions

Closed Positions

Activity History

Notifications

List Notifications

Drop Notifications

Portfolio Value

​Open Positions

​Closed Positions

​Activity History

​Notifications

​List Notifications

​Drop Notifications

​Portfolio Value

Open Positions

Closed Positions

Activity History

Notifications

List Notifications

Drop Notifications

Portfolio Value