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

# Positions

> Get one wallet's open Polymarket positions, with size, average entry price, and realized PnL for each outcome token.

```text theme={"dark"}
GET https://edge.goldsky.com/data/polymarket/positions
```

Returns one wallet's Polymarket positions on Polygon, one row per outcome token, largest first. Each row carries the position's size, average entry price, realized PnL, and total bought. Use it to build a portfolio view for a trader, or to rank a wallet's positions by PnL.

## Parameters

**address** `string` *required*

The wallet to look up: `0x` followed by 40 hex characters, in any case.

**token\_id** `string`

Comma-separated outcome token IDs. Only return positions in these tokens.

**min\_amount** `string` (default: 0)

Only return positions whose `amount` is greater than this value, in the same raw units as `amount`. The default leaves out closed positions.

**include\_zero** `boolean` (default: false)

Set to `true` to also return closed positions, whose `amount` is zero. When `true`, `min_amount` is ignored.

**sort** `string` (default: amount\_desc)

`amount_desc`, `amount_asc`, `realized_pnl_desc`, or `last_updated_at_desc`. Ties are broken by `token_id`, ascending. A `null` value sorts as zero, but comes back as `null`.

**limit** `integer` (default: 100)

Rows per page, up to `500`. See [pagination](https://docs.goldsky.com/feeds/api/overview.md#prediction-markets-and-chain-datasets).

**cursor** `string`

The `next_cursor` from a previous response. Use the same `sort` as the request that returned it.

## Response

**data** `object[]`

One entry per outcome token the wallet has a position in, in `sort` order.

**properties**

**address** `string`

The wallet address, in lowercase.

**token\_id** `string`

Outcome token ID.

**amount** `string | null`

Current position size, in shares, as a string in raw units of 10^6. `"12120000000"` is 12,120 shares.

**avg\_price** `string | null`

Average entry price, in USDC per share, as a string in raw units of 10^6. `"100000"` is \$0.10.

**realized\_pnl** `string | null`

Realized profit and loss, in USDC, as a string in raw units of 10^6.

**total\_bought** `string | null`

Total amount bought, as a string in raw units of 10^6.

**block\_number** `integer | null`

Polygon block of the position's most recent update.

**last\_updated\_at** `number | null`

When Goldsky last wrote the row, in Unix seconds with microsecond precision. It isn't the block time: two rows with different `block_number` values can share it.

**limit** `integer`

The page size used for this response.

**next\_cursor** `string | null`

Pass it as `cursor` to get the next page. `null` on the last page.

## How the data behaves

* **Numbers are raw strings.** `amount`, `avg_price`, `realized_pnl`, and `total_bought` come back as strings in raw units of 10^6, so no precision is lost. Divide by 1,000,000 before you show them. [Activity](https://docs.goldsky.com/feeds/api/prediction-markets/activity.md) is different: it returns plain JSON numbers already in shares and USDC.
* **A position isn't a balance.** `amount` is the net position from trades. The [Balances](https://docs.goldsky.com/feeds/api/prediction-markets/balances.md) feed returns the outcome tokens the wallet actually holds, which splits, merges, redeems, and plain transfers also change. The two can differ for the same token.
* **Positions are current.** You can't ask for a wallet's positions at a past block. Responses carry `Cache-Control: public, max-age=2`.
* **PnL is realized only.** `realized_pnl` doesn't include gains or losses on shares the wallet still holds.

## Errors

This endpoint returns the [same errors](https://docs.goldsky.com/feeds/api/overview.md#errors) as the other feeds. It returns `400 BAD_REQUEST` when `address` is missing or isn't 40 hex characters, when `sort` isn't one of the values above, or when `cursor` was issued for a different `sort`.

## Billing

With an API key, each row returned is one compute unit, at \$10 per million. An empty page is free. With [x402](https://docs.goldsky.com/feeds/api/overview.md#pay-per-request-with-x402), each request costs 10 atomic USDC (\$0.00001), however many rows it returns. See [Feeds pricing](https://docs.goldsky.com/pricing/summary.md#feeds).

## Example

Get a wallet's three largest positions:

```bash theme={"dark"}
curl -H "X-API-Key: $GOLDSKY_FEEDS_API_KEY" \
  "https://edge.goldsky.com/data/polymarket/positions?address=0x0000000000002d4249a9b7976dc47d3cff1a54a2&limit=3"
```

The response has this shape. The values are illustrative, and token IDs are shortened:

```json theme={"dark"}
{
  "data": [
    {
      "address": "0x0000000000002d4249a9b7976dc47d3cff1a54a2",
      "token_id": "10731…",
      "amount": "1520500000",
      "avg_price": "580000",
      "realized_pnl": "212400000",
      "total_bought": "3400000000",
      "block_number": 78412233,
      "last_updated_at": 1793208716.482113
    },
    {
      "address": "0x0000000000002d4249a9b7976dc47d3cff1a54a2",
      "token_id": "48211…",
      "amount": "800000000",
      "avg_price": "310000",
      "realized_pnl": "-15200000",
      "total_bought": "900000000",
      "block_number": 78398120,
      "last_updated_at": 1793180519.067341
    },
    {
      "address": "0x0000000000002d4249a9b7976dc47d3cff1a54a2",
      "token_id": "92065…",
      "amount": "125000000",
      "avg_price": "900000",
      "realized_pnl": "0",
      "total_bought": "125000000",
      "block_number": 78301877,
      "last_updated_at": 1792987322.904516
    }
  ],
  "next_cursor": "eyJzIjoiYW1vdW50X2Rlc2MiLCJrIjoiMTI1MDAwMDAwIiwi...",
  "limit": 3
}
```


## Related topics

- [Indexing Polymarket with Goldsky](https://docs.goldsky.com/chains/polymarket.md)
- [Curated dataset schemas: ERC-20, ERC-721, ERC-1155](https://docs.goldsky.com/turbo-pipelines/reference/schema/curated-schemas.md)
- [Solana sources for Turbo pipelines](https://docs.goldsky.com/turbo-pipelines/sources/solana.md)
- [Create no-code subgraphs](https://docs.goldsky.com/subgraphs/guides/create-a-no-code-subgraph.md)
- [Pricing: plans, metering, and product costs](https://docs.goldsky.com/pricing/summary.md)