User stories

Overview

User stories provide social trading context that enriches markets in the API response. Some markets include trading activity from notable traders, helping users discover interesting markets and understand trading dynamics.

Each user story contains user profile information (username, pseudonym), trade details (side, shares, price, timestamp), and P&L for that specific trade.

Selection Criteria

Not all markets have user stories. Stories are included when trades meet any of the following criteria:

Criterion	Threshold	Notes
Notable Traders	Total P&L > 5,000 USDC	OR
	P&L percentage > 20%	OR
	Total trading volume > 15,000 USDC
Large Bets	Individual bet > 1,000 USDC	Regardless of trader metrics
Minimum Trade Size	Trade size ≥ 100 USDC	Applies to all stories

Schema

User stories are returned in metadata.user_stories as an array. A single market can have multiple stories.

{
  "type": "trade",
  "user_name": "PNCSV",
  "user_pseudonym": "Smug-Kebab",
  "event": "TRADE",
  "outcome": "No",
  "timestamp": "2026-01-15 13:57:15.0",
  "side": "SELL",
  "usdc": 13504.94598,
  "shares": 13532.0,
  "price": 0.998,
  "user_pnl": -11.740894,
  "user_volume": 27140.081694,
  "user_pfp": ""
}

Field Descriptions

Field	Type	Description
`type`	string	Type of story (e.g., "trade")
`user_name`	string	Username of the trader
`user_pseudonym`	string	Display name/pseudonym for the user (e.g., "Smug-Kebab", "Reckless-Cilantro")
`event`	string	Event type (e.g., "TRADE")
`outcome`	string	Market outcome the user traded on ("Yes" or "No")
`timestamp`	string	When the trade occurred (format: "YYYY-MM-DD HH:MM:SS.S")
`side`	string	Trade side ("BUY" or "SELL")
`usdc`	number	Amount traded in USDC
`shares`	number	Number of shares traded
`price`	number	Price per share at time of trade (decimal, e.g., 0.998 = 99.8¢)
`user_pnl`	number	User's profit and loss on this specific trade (can be negative)
`user_volume`	number	User's total trading volume across all markets
`user_pfp`	string	User profile picture URL (empty string if none)

API Response Example

{
  "item_id": "1090479",
  "score": 0.13333333333333333,
  "metadata": {
    "question": "Trove FDV above $20M one day after launch?",
    "user_stories": [
      {
        "type": "trade",
        "user_name": "TheDJ",
        "user_pseudonym": "Reckless-Cilantro",
        "event": "TRADE",
        "outcome": "No",
        "timestamp": "2026-01-12 17:23:00.0",
        "side": "BUY",
        "usdc": 1008.0,
        "shares": 2100.0,
        "price": 0.48,
        "user_pnl": 84.0,
        "user_volume": 4056.0,
        "user_pfp": ""
      },
      {
        "type": "trade",
        "user_name": "Daoxialiuren",
        "user_pseudonym": "Political-Interconnection",
        "event": "TRADE",
        "outcome": "No",
        "timestamp": "2026-01-12 17:58:00.0",
        "side": "BUY",
        "usdc": 351.35,
        "shares": 651.0,
        "price": 0.54,
        "user_pnl": -13.35,
        "user_volume": 20556.0,
        "user_pfp": ""
      }
    ]
  }
}

P&L Calculation

P&L represents profit or loss on that specific trade: P&L = (current_price - entry_price) × shares

Note: This is the P&L for the specific trade, not the user's total P&L across all positions.

Using User Stories

When a market includes user stories, you can select one story arbitrarily (e.g., first in array) or use heuristics:

Most recent trade (timestamp)
Largest trade size (usdc)
Highest P&L (user_pnl)
Top trader by volume (user_volume)

Note: Not all markets have user stories. Check if metadata.user_stories exists and is not empty.