> ## 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.

# Prediction markets Balances

> Get the Polymarket outcome tokens one wallet holds, with the balance of each and the block of its last change.

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

Returns the Polymarket outcome tokens one wallet holds on Polygon, one row per token, with the latest balance of each. These are the ERC-1155 tokens of Polymarket's Conditional Tokens contract. Use it to check what a wallet holds right now, whatever trades, splits, merges, or transfers got it there.

This is a different feed from the wallet [Balances](https://docs.goldsky.com/feeds/api/balances.md) feed, which returns native and ERC-20 balances with USD values.

## 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 balances of these tokens.

**contract\_address** `string`

Only return balances of tokens issued by this contract: `0x` followed by 40 hex characters.

**token\_type** `string`

Only return balances of this token type, such as `ERC_1155`. Case-sensitive.

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

Only return balances at or above this value, in the same raw units as `balance`. The default includes balances that have dropped to zero. Set `min_balance=1` to leave them out.

**as\_of\_block** `integer`

Return the latest balance Goldsky recorded at or before this Polygon block. It isn't an exact reconstruction of the chain at that block: events Goldsky processed late or out of order may not be reflected.

**sort** `string` (default: block\_timestamp\_desc)

`block_timestamp_desc`, most recently changed first, or `balance_desc`, largest first. Ties are broken by `token_id`, ascending.

**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, in `sort` order.

**properties**

**address** `string`

The wallet address, in lowercase.

**token\_id** `string`

Outcome token ID.

**contract\_address** `string | null`

Contract that issued the token.

**token\_type** `string | null`

Token standard, such as `ERC_1155`.

**balance** `string`

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

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

Polygon block of the balance's most recent change.

**block\_timestamp** `integer | null`

Time of `block_number`, in Unix seconds.

**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

* **A balance isn't a position.** `balance` is what the wallet holds onchain. [Positions](https://docs.goldsky.com/feeds/api/prediction-markets/positions.md) returns the net position from trades, which can differ, because splits, merges, redeems, and plain transfers move tokens without a trade.
* **Balances are raw strings.** Divide `balance` by 1,000,000 before you show it.
* **Caching follows the block.** Responses carry `Cache-Control: public, max-age=2`. With `as_of_block`, they carry `public, max-age=86400, immutable`.

## 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, when `address` or `contract_address` 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 two largest nonzero balances:

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

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

```json theme={"dark"}
{
  "data": [
    {
      "address": "0x0000000000002d4249a9b7976dc47d3cff1a54a2",
      "token_id": "10731…",
      "contract_address": "0x4d97dcd97ec945f40cf65f87097ace5ea0476045",
      "token_type": "ERC_1155",
      "balance": "1520500000",
      "block_number": 78412233,
      "block_timestamp": 1793208713
    },
    {
      "address": "0x0000000000002d4249a9b7976dc47d3cff1a54a2",
      "token_id": "48211…",
      "contract_address": "0x4d97dcd97ec945f40cf65f87097ace5ea0476045",
      "token_type": "ERC_1155",
      "balance": "800000000",
      "block_number": 78398120,
      "block_timestamp": 1793180517
    }
  ],
  "next_cursor": "eyJzIjoiYmFsYW5jZV9kZXNjIiwiayI6IjgwMDAwMDAwMCIsInQiOiI0...",
  "limit": 2
}
```


## Related topics

- [Feeds: ready-made onchain datasets](https://docs.goldsky.com/feeds.md)
- [Feeds API overview](https://docs.goldsky.com/feeds/api/overview.md)
- [Build with agents](https://docs.goldsky.com/feeds/agents.md)
- [Build a binary prediction market](https://docs.goldsky.com/compose/guides/build-a-prediction-market.md)
- [Pricing: plans, metering, and product costs](https://docs.goldsky.com/pricing/summary.md)