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

> ## Agent Instructions
> API requests use the base URL https://api.unusualwhales.com and require a bearer token in the `Authorization` header (`Authorization: Bearer <API_KEY>`). Create and manage API tokens at https://unusualwhales.com/dashboard/api.
> For live market data inside an AI tool, use the Unusual Whales MCP server at https://unusualwhales.com/public-api/mcp.
> Instructions for agents using Unusual Whales tools: https://unusualwhales.com/skill.md

# PredictionsPosition

> Snapshot of a user's position in a single outcome token, published to the `predictions-positions` Kafka topic every time the position changes on-chain. Each message carries the full new state of the position, not a delta. Prices and USD amounts are denominated in USDC; token amounts are in outcome tokens (shares), where one winning share redeems for $1.

Message
fields**15**
topic[predictions-positions](/docs/kafka/topics/predictions-positions.md)

**Proto definition**

```protobuf schema.proto theme={null}
message PredictionsPosition {
  int64 user_id = 1;
  int64 asset_id = 2;
  string user_address = 3;
  string asset_address = 4;
  Decimal amount = 5;
  Decimal avg_price = 6;
  Decimal invested_usd = 7;
  Decimal realized_pnl = 8;
  Decimal total_bought = 9;
  Decimal total_invested_usd = 10;
  int64 updated_at = 11;
  optional int64 first_traded_at = 12;
  int64 last_block = 13;
  int64 block_start = 14;
  int64 block_end = 15;
}
```

## Fields

The number on the right of each row is the protobuf field number.

user\_id
int64
1

Internal numeric id of the user's wallet. Same id space as PredictionsTrade.maker\_id/taker\_id and PredictionsInsider.user\_id.

asset\_id
int64
2

Internal numeric id of the outcome token. Same id space as PredictionsTrade.asset\_id and PredictionsInsider.asset\_id.

user\_address
string
3

User wallet address (0x-prefixed hex).

asset\_address
string
4

Polymarket CTF (ERC-1155) token id of the outcome token, as a decimal string. Note: despite the name this is a token id, not a 0x contract address. It matches PredictionsTrade.asset\_address and PredictionsInsider.token\_id.

amount
[Decimal](/docs/kafka/types/Decimal.md)
5

Outcome tokens (shares) currently held.

avg\_price
[Decimal](/docs/kafka/types/Decimal.md)
6

Average entry price per share of the current holding, in USDC (between 0 and 1).

invested\_usd
[Decimal](/docs/kafka/types/Decimal.md)
7

Cost basis of the current holding, in USDC (amount \* avg\_price).

realized\_pnl
[Decimal](/docs/kafka/types/Decimal.md)
8

Cumulative realized profit or loss from sells and redemptions of this token, in USDC.

total\_bought
[Decimal](/docs/kafka/types/Decimal.md)
9

Cumulative shares of this token ever bought. Unlike `amount`, this does not decrease when shares are sold.

total\_invested\_usd
[Decimal](/docs/kafka/types/Decimal.md)
10

Cumulative USDC ever spent buying this token. Unlike `invested_usd`, this does not decrease when shares are sold.

updated\_at
int64
11

Currently not populated (always 0). Reserved for the time the position was last updated.

first\_traded\_at
int64
optional
12

Approximate time of the user's first trade in this token, Unix epoch milliseconds, UTC. Estimated from the block number using the average Polygon block time, so it can drift by a few minutes.

last\_block
int64
13

Polygon block number at which this position state took effect. In this stream it equals block\_start.

block\_start
int64
14

First Polygon block of the range in which this position state is valid (inclusive).

block\_end
int64
15

Last Polygon block of the validity range (exclusive). 0 while this is the latest state of the position.