Skip to main content

​
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

MethodEndpointDescription
GET/v1/portfolio/positionsGet user’s trading positions

​
Activities

MethodEndpointDescription
GET/v1/portfolio/activitiesGet trading activity history

​
Account

MethodEndpointDescription
GET/v1/account/balancesGet 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

FieldTypeDescription
netPositionDecimalstring (decimal)Net position quantity in contracts (positive = long, negative = short)
qtyBoughtDecimalstring (decimal)Total quantity bought in contracts
qtySoldDecimalstring (decimal)Total quantity sold in contracts
qtyAvailableDecimalstring (decimal)Quantity available to trade in contracts
bodPositionDecimalstring (decimal)Beginning of day position in contracts
netPositionstring (int64)Deprecated rounded quantity; use netPositionDecimal
qtyBoughtstring (int64)Deprecated rounded quantity; use qtyBoughtDecimal
qtySoldstring (int64)Deprecated rounded quantity; use qtySoldDecimal
costAmountTotal cost basis
realizedAmountRealized profit/loss
cashValueAmountCurrent unrealized value
qtyAvailablestring (int64)Deprecated rounded quantity; use qtyAvailableDecimal
bodPositionstring (int64)Deprecated rounded quantity; use bodPositionDecimal
expiredbooleanWhether the position has expired
updateTimestring (date-time)Last update timestamp
marketMetadataobjectMarket 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:
TypeNested FieldDescription
ACTIVITY_TYPE_TRADEtradeTrade execution details
ACTIVITY_TYPE_POSITION_RESOLUTIONpositionResolutionMarket settlement details
ACTIVITY_TYPE_ACCOUNT_DEPOSITaccountBalanceChangeDeposit details
ACTIVITY_TYPE_ACCOUNT_ADVANCED_DEPOSITaccountBalanceChangeAdvance issued against a pending deposit
ACTIVITY_TYPE_ACCOUNT_WITHDRAWALaccountBalanceChangeWithdrawal details
ACTIVITY_TYPE_TRANSFERaccountBalanceChangeTransfer details
ACTIVITY_TYPE_REFERRAL_BONUSaccountBalanceChangeReferral incentive credit
ACTIVITY_TYPE_TAKER_FEE_REBATEaccountBalanceChangeTaker fee rebate credit
ACTIVITY_TYPE_LIQUIDITY_PROGRAMaccountBalanceChangeLiquidity program payout

​
Trade Object

FieldTypeDescription
idstringExchange-assigned trade ID
marketSlugstringMarket slug
statestringTrade state (CLEARED, BUSTED, etc.)
priceAmountTrade price
qtyDecimalstring (decimal)Trade quantity in contracts
qtystringDeprecated rounded quantity; use qtyDecimal
isAggressorbooleanTrue if user’s order was the taker
costBasisAmountCost basis for the trade
realizedPnlAmountRealized profit/loss
createTimestring (date-time)Creation timestamp
updateTimestring (date-time)Last update timestamp

​
Position Resolution Object

FieldTypeDescription
marketSlugstringMarket slug
beforePositionUserPositionPosition before resolution
afterPositionUserPositionPosition after resolution
sidestringResolution side (LONG, SHORT, NEUTRAL)
tradeIdstringAssociated trade ID
updateTimestring (date-time)Resolution timestamp

​
Account Balance Change Object

FieldTypeDescription
transactionIdstringTransaction ID
statusstringStatus (PENDING, COMPLETED, REJECTED)
amountAmountAmount of the balance change
createTimestring (date-time)Creation timestamp
updateTimestring (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 OrderDescription
SORT_ORDER_DESCENDINGNewest first (default)
SORT_ORDER_ASCENDINGOldest 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

FieldDescription
currentBalanceCurrent fiat currency balance
currencyCurrency code (e.g., USD)
buyingPowerCapital available for trading
assetNotionalTotal notional value of securities
assetAvailableAvailable collateral value
pendingCreditPending credit amounts
openOrdersValue tied up in open orders
unsettledFundsUnsettled funds not yet available
marginRequirementRequired 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.