Documentation Index
Fetch the complete documentation index at: https://docs.polymarket.us/llms.txt
Use this file to discover all available pages before exploring further.
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": "100",
"qtyBought": "100",
"qtySold": "0",
...
},
"another-market": {
"netPosition": "-50",
...
}
},
"nextCursor": "abc123",
"eof": false
}
Position Fields
| Field | Type | Description |
|---|
netPosition | string (int64) | Net position quantity (positive = long, negative = short) |
qtyBought | string (int64) | Total quantity bought |
qtySold | string (int64) | Total quantity sold |
cost | Amount | Total cost basis |
realized | Amount | Realized profit/loss |
cashValue | Amount | Current unrealized value |
qtyAvailable | string (int64) | Quantity available to trade |
bodPosition | string (int64) | Beginning of day position |
expired | boolean | Whether the position has expired |
updateTime | string (date-time) | Last update timestamp |
marketMetadata | object | Market 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:
| 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_WITHDRAWAL | accountBalanceChange | Withdrawal details |
ACTIVITY_TYPE_TRANSFER | accountBalanceChange | Transfer details |
Trade Object
| Field | Type | Description |
|---|
id | string | Exchange-assigned trade ID |
marketSlug | string | Market slug |
state | string | Trade state (CLEARED, BUSTED, etc.) |
price | Amount | Trade price |
qty | string | Trade quantity |
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 |
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 |
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. 
