Message

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.

fields15 topicpredictions-positions

▶Proto definition.proto

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

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 5

Outcome tokens (shares) currently held.

avg_price Decimal 6

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

invested_usd Decimal 7

Cost basis of the current holding, in USDC (amount * avg_price).

realized_pnl Decimal 8

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

total_bought Decimal 9

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

total_invested_usd Decimal 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.