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 Ed25519 signature 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": "100",
      "qtyBought": "100",
      "qtySold": "0",
      ...
    },
    "another-market": {
      "netPosition": "-50",
      ...
    }
  },
  "nextCursor": "abc123",
  "eof": false
}

​
Position Fields

FieldTypeDescription
netPositionstring (int64)Net position quantity (positive = long, negative = short)
qtyBoughtstring (int64)Total quantity bought
qtySoldstring (int64)Total quantity sold
costAmountTotal cost basis
realizedAmountRealized profit/loss
cashValueAmountCurrent unrealized value
qtyAvailablestring (int64)Quantity available to trade
bodPositionstring (int64)Beginning of day position
expiredbooleanWhether the position has expired
updateTimestring (date-time)Last update timestamp
marketMetadataobjectMarket information (slug, title, outcome)

​
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_WITHDRAWALaccountBalanceChangeWithdrawal details
ACTIVITY_TYPE_TRANSFERaccountBalanceChangeTransfer details

​
Trade Object

FieldTypeDescription
idstringExchange-assigned trade ID
marketSlugstringMarket slug
statestringTrade state (CLEARED, BUSTED, etc.)
priceAmountTrade price
qtystringTrade quantity
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.