Portfolio API

The Portfolio API provides access to user positions, account balances, and trading activity history.

Authentication RequiredAll Portfolio API endpoints require API key authentication. See the Authentication guide for details on signing requests.

Base URL

https://api.polymarket.us

Endpoints

Positions

Method	Endpoint	Description
`GET`	`/v1/portfolio/positions`	Get user’s trading positions

Activities

Method	Endpoint	Description
`GET`	`/v1/portfolio/activities`	Get trading activity history

Account

Method	Endpoint	Description
`GET`	`/v1/account/balances`	Get account balances

Positions Response

The positions response returns a map of market slug to position, not an array:

{
  "positions": {
    "will-x-happen": {
      "netPosition": "20",
      "netPositionDecimal": "19.6000",
      "qtyBought": "20",
      "qtyBoughtDecimal": "19.6000",
      "qtySold": "0",
      "qtySoldDecimal": "0.0000",
      ...
    },
    "another-market": {
      "netPosition": "-50",
      ...
    }
  },
  "nextCursor": "abc123",
  "eof": false
}

Position Fields

Field	Type	Description
`netPositionDecimal`	string (decimal)	Net position quantity in contracts (positive = long, negative = short)
`qtyBoughtDecimal`	string (decimal)	Total quantity bought in contracts
`qtySoldDecimal`	string (decimal)	Total quantity sold in contracts
`qtyAvailableDecimal`	string (decimal)	Quantity available to trade in contracts
`bodPositionDecimal`	string (decimal)	Beginning of day position in contracts
`netPosition`	string (int64)	Deprecated rounded quantity; use `netPositionDecimal`
`qtyBought`	string (int64)	Deprecated rounded quantity; use `qtyBoughtDecimal`
`qtySold`	string (int64)	Deprecated rounded quantity; use `qtySoldDecimal`
`cost`	Amount	Total cost basis
`realized`	Amount	Realized profit/loss
`cashValue`	Amount	Current unrealized value
`qtyAvailable`	string (int64)	Deprecated rounded quantity; use `qtyAvailableDecimal`
`bodPosition`	string (int64)	Deprecated rounded quantity; use `bodPositionDecimal`
`expired`	boolean	Whether the position has expired
`updateTime`	string (date-time)	Last update timestamp
`marketMetadata`	object	Market information (slug, title, outcome)

Use the *Decimal quantity fields for display and calculations. The older integer fields remain for backward compatibility and should not be used for partial-contract markets.

Activities Response

Activities are returned as an array with pagination:

{
  "activities": [
    {
      "type": "ACTIVITY_TYPE_TRADE",
      "trade": { ... }
    }
  ],
  "nextCursor": "xyz789",
  "eof": false
}

Activity Structure

Each activity has a type field and a corresponding nested object:

Type	Nested Field	Description
`ACTIVITY_TYPE_TRADE`	`trade`	Trade execution details
`ACTIVITY_TYPE_POSITION_RESOLUTION`	`positionResolution`	Market settlement details
`ACTIVITY_TYPE_ACCOUNT_DEPOSIT`	`accountBalanceChange`	Deposit details
`ACTIVITY_TYPE_ACCOUNT_ADVANCED_DEPOSIT`	`accountBalanceChange`	Advance issued against a pending deposit
`ACTIVITY_TYPE_ACCOUNT_WITHDRAWAL`	`accountBalanceChange`	Withdrawal details
`ACTIVITY_TYPE_TRANSFER`	`accountBalanceChange`	Transfer details
`ACTIVITY_TYPE_REFERRAL_BONUS`	`accountBalanceChange`	Referral incentive credit
`ACTIVITY_TYPE_TAKER_FEE_REBATE`	`accountBalanceChange`	Taker fee rebate credit
`ACTIVITY_TYPE_LIQUIDITY_PROGRAM`	`accountBalanceChange`	Liquidity program payout

Trade Object

Field	Type	Description
`id`	string	Exchange-assigned trade ID
`marketSlug`	string	Market slug
`state`	string	Trade state; see Trade States
`price`	Amount	Trade price
`qtyDecimal`	string (decimal)	Trade quantity in contracts
`qty`	string	Deprecated rounded quantity; use `qtyDecimal`
`isAggressor`	boolean	True if user’s order was the taker
`costBasis`	Amount	Cost basis for the trade
`realizedPnl`	Amount	Realized profit/loss
`createTime`	string (date-time)	Creation timestamp
`updateTime`	string (date-time)	Last update timestamp

Trade States

The state field on a trade progresses through the following values:

State	Value	Description
`TRADE_STATE_NEW`	1	Trade created.
`TRADE_STATE_CLEARED`	2	Trade successfully cleared by the clearing house.
`TRADE_STATE_BUSTED`	3	The trade was voided post-execution by the exchange (an error trade) and the resulting position was rolled back. This is a terminal reversal, not a pending state.
`TRADE_STATE_INFLIGHT`	4	Trade information sent to the clearinghouse.
`TRADE_STATE_PENDING_RISK`	5	Clearinghouse is pending at least one DCM claim for the trade.
`TRADE_STATE_PENDING_CLEARED`	6	Clearinghouse is pending the counterparty DCM claim.
`TRADE_STATE_REJECTED`	7	Clearinghouse rejected the trade.
`TRADE_STATE_CLEARING_ACKNOWLEDGED`	8	Clearing request acknowledged by the clearing house.
`TRADE_STATE_RETRY_REQUEST`	9	Retry requested; pending resubmission to the clearing house.

Handling TRADE_STATE_BUSTEDA busted trade was executed and then voided by the exchange (via an error-trade bust), and its position impact was reversed. Busted trades remain visible in trade history — treat them as reversed for position, P&L, and reconciliation purposes. Do not silently drop them.

TRADE_STATE_UNDEFINED (value 0) is the unset/unknown sentinel. It is omitted from API responses and does not appear in the published enum lists. Treat any unrecognized state value defensively rather than assuming the values above are exhaustive.

Position Resolution Object

Field	Type	Description
`marketSlug`	string	Market slug
`beforePosition`	UserPosition	Position before resolution
`afterPosition`	UserPosition	Position after resolution
`side`	string	Resolution side (LONG, SHORT, NEUTRAL)
`tradeId`	string	Associated trade ID
`updateTime`	string (date-time)	Resolution timestamp

Account Balance Change Object

Field	Type	Description
`transactionId`	string	Transaction ID
`status`	string	Status (PENDING, COMPLETED, REJECTED)
`amount`	Amount	Amount of the balance change
`createTime`	string (date-time)	Creation timestamp
`updateTime`	string (date-time)	Last update timestamp

Pagination

Both endpoints support cursor-based pagination. Use cursor parameter with the nextCursor value to fetch the next page. When eof is true, there are no more results.

Real-Time Position UpdatesFor real-time position changes, use the WebSocket Private Stream with the SUBSCRIPTION_TYPE_POSITION subscription instead of polling.

Filtering Activities

Filter activities by type and market:

GET /v1/portfolio/activities?types=ACTIVITY_TYPE_TRADE&marketSlug=will-x-happen

Sort Order

Activities can be sorted ascending or descending by time:

Sort Order	Description
`SORT_ORDER_DESCENDING`	Newest first (default)
`SORT_ORDER_ASCENDING`	Oldest first

Account Balances

The account balances endpoint returns current balance information:

{
  "balances": [
    {
      "currentBalance": 1000.00,
      "currency": "USD",
      "buyingPower": 850.00,
      "assetNotional": 500.00,
      "assetAvailable": 250.00,
      "openOrders": 400.00,
      "unsettledFunds": 0,
      "marginRequirement": 0,
      "lastUpdated": "2024-01-15T10:30:00Z"
    }
  ]
}

Balance Fields

Field	Description
`currentBalance`	Current fiat currency balance
`currency`	Currency code (e.g., USD)
`buyingPower`	Capital available for trading
`assetNotional`	Total notional value of securities
`assetAvailable`	Available collateral value
`pendingCredit`	Pending credit amounts
`openOrders`	Value tied up in open orders
`unsettledFunds`	Unsettled funds not yet available
`marginRequirement`	Required margin for positions

Buying Power

The buyingPower field represents unencumbered capital available for trading:

buyingPower = currentBalance
            + assetAvailable
            - openOrders
            - marginRequirement

Real-Time Balance UpdatesFor real-time balance changes, use the WebSocket Private Stream with the SUBSCRIPTION_TYPE_ACCOUNT_BALANCE subscription instead of polling.

Getting Started

Orders

Portfolio

Events

Markets

Series

Sports

Sports (Legacy)

Tags

Search

Incentives

Portfolio API Overview

Portfolio API

Base URL

Endpoints

Positions

Activities

Account

Positions Response

Position Fields

Activities Response

Activity Structure

Trade Object

Trade States

Position Resolution Object

Account Balance Change Object

Filtering Activities

Sort Order

Account Balances

Balance Fields

Buying Power

​Portfolio API

​Base URL

​Endpoints

​Positions

​Activities

​Account

​Positions Response

​Position Fields

​Activities Response

​Activity Structure

​Trade Object

​Trade States

​Position Resolution Object

​Account Balance Change Object

​Pagination

​Filtering Activities

​Sort Order

​Account Balances

​Balance Fields

​Buying Power

Portfolio API

Base URL

Endpoints

Positions

Activities

Account

Positions Response

Position Fields

Activities Response

Activity Structure

Trade Object

Trade States

Position Resolution Object

Account Balance Change Object

Pagination

Filtering Activities

Sort Order

Account Balances

Balance Fields

Buying Power