Market cards

Market cards are ❜embed's way to display all the important information users need to browse feeds and take trading actions. Visit the console Feed Builder to see them in action.

This guide explains each field available in the market card metadata and where it appears on the card. In the future we hope to make these cards available through our SDK.

Market Card Layout

┌─────────────────────────────────────────────────────────────────┐
│  [Question Text]                    [Categories]  [Relevance]   │
│  "Fed increases interest rates by 25+ bps after January 2026    │
│   meeting?"                       General • Markets • 2025      │
│                                                      Relevance  │
│                                                      1.000      │
├─────────────────────────────────────────────────────────────────┤
│  [User Profile]  [Username]  [Tags]  [Timestamp]  [P&L Status]  │
│     (👤)         LizWillis  Utilized-Orchid  Jan 15, 16:07      │
│                                                      Highlighted│
│                                                      Loss       │
│                                                                 │
│  [Betting Action]                                               │
│  Betting $13,544.20 on NO                                       │
│  Entry 100¢ → Now 100¢                                          │
│  P&L -0.76 USDC -0.01%                                          │
├─────────────────────────────────────────────────────────────────┤
│  [Market Image]          [Betting Buttons]                      │
│  [Jerome Powell]         YES: 0¢    NO: 100¢                    │
│  image                   [Button]  [Button]                     │
├─────────────────────────────────────────────────────────────────┤
│  [Market Status]  [24h Vol]  [Spread]  [Progress]  [Time Left]  │
│  ACTIVE           24h Vol    Spread    [━━━━━━━━]  12 days      │
│                   $20,274,185 0.001              remaining      │
├─────────────────────────────────────────────────────────────────┤
│  > Show 9 more interesting bets                                 │
├─────────────────────────────────────────────────────────────────┤
│  AI Labels (Debug)                                              │
│  Features (f): informative, neutral, educative                  │
│  Topics (t): science technology                                 │
└─────────────────────────────────────────────────────────────────┘

Field Mapping

Market Card Fields

Question (question)

The prediction question that defines the market outcome. Traders position by buying "YES" or "NO" shares based on whether they believe the outcome will occur.

Example:

"question": "Fed increases interest rates by 25+ bps after January 2026 meeting?"

Relevance Score (score)

The relevance score indicates how well this market matches the feed configuration and user context. It is highly influenced by the scoring function chosen at the ranking step. Higher scores indicate better matches.

Note: When scoring: "none" is set, the score is based on a normalization of the order_by field value.

P&L (Profit & Loss)

The user's profit or loss on their position in this market. Important: This is not true P&L, but rather the difference between the entry price and the current price.

Calculation: P&L = (current_price - entry_price) × shares

Example:

• Entry price: 100¢
• Current price: 100¢
• P&L: -0.96 USDC (-0.01%)

Market Status (ignore)

Note: Market status flags (active, closed, archived, featured, restricted, approved) in the API response should be ignored. These fields are present in the response but are not reliable indicators of market status. All markets returned in the response will be active or closed according to the filters set in the feed config.

24h Volume (volume_24hr)

Total volume of trades executed on this market in the past 24 hours, measured in USD.

Example:

"volume_24hr": 20274.0

Display: "24h Vol $20,274"

Spread (spread)

The current spread on the "YES" share of this market. Spread represents the difference between the best bid and best ask prices.

Example:

"spread": 0.01

Display: "Spread 0.01"

Time Left (time_left)

Number of days remaining before this market is estimated to come to an end and resolve.

Example:

"end_date": "2026-01-27T01:00:00"

Display: "12 days remaining"

AI Labels (ai_labels)

Labels automatically generated by Embed's AI system, reflecting topics, features, or categories for markets. These help classify and organize markets for better discovery and filtering.

Label categories:

• Topics (t): science_technology, sports, business_entrepreneurs, etc.
• Features (f): informative, neutral, educative, prediction, etc.
• Categories (c): crypto, sports, chains, etc.

Example:

"ai_labels": [
  "mbd2_f_informative",
  "mbd2_f_neutral",
  "mbd2_f_educative",
  "mbd2_t_science_technology",
  "tba2_c_crypto"
]

Display: "Features (f): informative, neutral, educative" and "Topics (t): science technology"

User Stories (user_stories)

Trading activity and stories from other users on this market. User stories show recent trades, positions, and outcomes from other traders, providing social context and market activity insights.

Note: See the User Story Guide for detailed information about user stories.

Example:

"user_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": ""
  }
]

User Story Fields:

• type - Type of story (e.g., "trade")
• user_name - Username of the trader
• user_pseudonym - Display name/pseudonym for the user
• event - Event type (e.g., "TRADE")
• outcome - Market outcome the user traded on ("Yes" or "No")
• timestamp - When the trade occurred
• side - Trade side ("BUY" or "SELL")
• usdc - Amount in USDC
• shares - Number of shares traded
• price - Price per share
• user_pnl - User's profit and loss on this trade
• user_volume - User's total trading volume
• user_pfp - User profile picture URL (empty string if none)

Complete Market Card Example

{
  "item_id": "1090479",
  "score": 0.13333333333333333,
  "metadata": {
    "question": "Record crypto liquidation in 2026?",
    "active": true,
    "closed": false,
    "archived": false,
    "volume_24hr": 1026.624911,
    "spread": 0.03,
    "end_date": "2027-01-01T05:00:00",
    "ai_labels": [
      "mbd2_f_informative",
      "mbd2_t_science_technology",
      "tba2_c_crypto"
    ],
    "user_stories": [...]
  }
}

Field Availability

Always available:

• question
• active, closed, archived
• volume_24hr
• spread
• end_date (for calculating time_left)

Conditional:

• score - Available when scoring is enabled; may be null when scoring: "none"
• ai_labels - Available when AI labeling is enabled
• user_stories - Available when market has trading activity
• P&L - Only shown for markets where the user has an active position