> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octav.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Polymarket Positions API

> Read the current Polymarket prediction market positions and collateral balance of a Polymarket wallet, in the portfolio format.

Read the prediction market positions a Polymarket wallet currently holds, and the collateral (USDC, pUSD) in it, on Polygon. This endpoint only reads positions; it does not place or open any. The response uses the same format as the [Portfolio endpoint](https://docs.octav.fi/api/endpoints/portfolio.md), with only the Polymarket protocol.

> [!NOTE]
>
> **Cost:** 1 credit per call

> [!WARNING]
>
> **Pass the Polymarket wallet itself.** Polymarket holds positions in a proxy wallet (the address shown on your Polymarket profile), not in the wallet you sign in with. This endpoint reads the address you pass as-is and does not look up the proxy wallet of a regular wallet, so a regular wallet returns no positions.

> [!NOTE]
>
> **Interactive Playground:** Test this endpoint in the [API Playground](https://docs.octav.fi/api-reference/polymarket/polymarket-positions.md). Get your API key at [data.octav.fi](https://data.octav.fi/)

***

## Endpoint

```bash theme={null}
GET https://api.octav.fi/v1/portfolio/proxy/polymarket
```

### Parameters

**addresses** `string` *required*

Polymarket (proxy) wallet address on Polygon. Only one address is accepted per call; a comma-separated list returns `400 Multiple addresses not supported yet`.

```
addresses=0x1234567890abcdef1234567890abcdef12345678
```

**aggregated** `boolean` (default: false)

Return the portfolio without the `address` field. The endpoint takes one address, so there is nothing to combine and the positions are unchanged.

***

## Example

```bash cURL theme={null}
curl "https://api.octav.fi/v1/portfolio/proxy/polymarket?addresses=0x1234567890abcdef1234567890abcdef12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const address = '0x1234567890abcdef1234567890abcdef12345678';

const response = await fetch(
  `https://api.octav.fi/v1/portfolio/proxy/polymarket?addresses=${address}`,
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);

const [portfolio] = await response.json();
console.log(`Polymarket value: $${portfolio.networth}`);
```

```python Python theme={null}
address = '0x1234567890abcdef1234567890abcdef12345678'

response = requests.get(
    'https://api.octav.fi/v1/portfolio/proxy/polymarket',
    params={'addresses': address},
    headers={'Authorization': f'Bearer {api_key}'}
)

portfolio = response.json()[0]
print(f"Polymarket value: ${portfolio['networth']}")
```

***

## Response

Returns an array holding one portfolio object. Positions are fetched live from Polymarket on every call.

### Top-Level Fields

**address** `string`

The wallet address (left out when `aggregated=true`)

**networth** `string`

Total value of the current positions and collateral, in USD

**assetByProtocols** `object`

Contains a single `polymarket` key. Its `chains.polygon.protocolPositions` groups positions by type:

* `VAULT`: current market positions, one per market outcome, named `"<market title> - <outcome>"` and valued at the position's current value
* `WALLET`: collateral (USDC, pUSD) sitting in the Polymarket wallet, named `"Polymarket Wallet"`

Each group carries a `proxyAddress` field with the Polymarket wallet.

**chains** `object`

Chain-level summary (Polygon only)

***

## Example Response

```json theme={null}
[
  {
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "networth": "214.15",
    "assetByProtocols": {
      "polymarket": {
        "name": "Polymarket",
        "key": "polymarket",
        "value": "214.15",
        "chains": {
          "polygon": {
            "name": "Polygon",
            "key": "polygon",
            "value": "214.15",
            "protocolPositions": {
              "VAULT": {
                "proxyAddress": "0x1234567890abcdef1234567890abcdef12345678",
                "totalValue": "100.00",
                "protocolPositions": [
                  {
                    "name": "Will it rain in New York on December 1? - Yes",
                    "value": "100.00",
                    "assets": [
                      { "symbol": "pusd", "name": "polymarket usd", "balance": "100.00", "price": "1", "value": "100.00" }
                    ]
                  }
                ]
              },
              "WALLET": {
                "name": "Wallet",
                "proxyAddress": "0x1234567890abcdef1234567890abcdef12345678",
                "totalValue": "114.15",
                "protocolPositions": [
                  {
                    "name": "Polymarket Wallet",
                    "value": "98.11",
                    "assets": [
                      { "symbol": "usdc", "name": "usd coin", "balance": "98.11", "price": "1", "value": "98.11" }
                    ]
                  },
                  {
                    "name": "Polymarket Wallet",
                    "value": "16.04",
                    "assets": [
                      { "symbol": "pusd", "name": "polymarket usd", "balance": "16.04", "price": "1", "value": "16.04" }
                    ]
                  }
                ]
              }
            }
          }
        }
      }
    },
    "chains": {
      "polygon": { "name": "Polygon", "key": "polygon", "chainId": "137", "value": "214.15", "valuePercentile": "100" }
    }
  }
]
```

> [!NOTE]
>
> Trimmed for readability: assets also carry `chainContract`, `contract`, `decimal`, images and P\&L fields, as on the [Portfolio endpoint](https://docs.octav.fi/api/endpoints/portfolio.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.