Skip to main content

Glossary

A comprehensive reference of key terms and concepts used throughout the Prediction Market API.

Core Concepts​

Market​

A prediction market represents a question about a future event with a defined set of possible outcomes. Markets go through a lifecycle from creation to settlement. Examples: "Will it rain tomorrow?", "Which team wins the final?"

Outcome​

An outcome is one of the possible results of a market. Each market has two or more outcomes. For a binary market like "Will Bitcoin hit $100K?", the outcomes would be "Yes" and "No". Shares are bought and sold per outcome.

Operator​

An operator is a registered business entity that integrates with the prediction market platform. Operators manage their own players, sessions, and wallets. Each operator has a unique API key for authentication. All data (markets, orders, positions) is scoped to the operator.

Player​

A player is an end-user of an operator's platform. Players are identified by a playerId string that the operator provides when placing orders. The prediction engine stores this identifier on orders but does not manage player accounts — that is the operator's responsibility.

Trading Concepts​

Order​

An instruction to buy or sell shares of a specific outcome. An order specifies the outcome, direction (buy/sell), quantity (shares), and optionally a price limit. Orders are submitted by operators on behalf of their players.

Order Side​

The direction of an order:

  • BUY — Acquire shares of an outcome. You profit if the outcome wins.
  • SELL — Dispose of shares you already hold. You lock in your current profit or loss.

Order Type​

How the order should be executed:

  • LIMIT — Execute only at the specified price or better. If no matching orders exist at your price, the order sits in the order book until matched or cancelled.
  • MARKET — Execute immediately at the best available price. Market orders are filled against existing limit orders in the book. If there is insufficient liquidity, the order may be partially filled or rejected.

Shares​

The unit of trading in a prediction market. Each share represents a claim on one unit of payout if the associated outcome wins. For example, buying 100 shares of "Yes" at $0.60 means you pay $60 and receive $100 if "Yes" wins, or $0 if it loses.

Price​

The cost per share, expressed as a value between 0.01 and 0.99. The price reflects the market's implied probability of the outcome occurring. A price of 0.65 implies a 65% probability. Prices are required for limit orders.

Spread​

The difference between the best ask (lowest sell price) and the best bid (highest buy price). A smaller spread indicates a more liquid market. For example, if the best bid is 0.63 and the best ask is 0.67, the spread is 0.04.

Trade​

A trade is created when a buy order is matched with a sell order. Each trade records the execution price, number of shares exchanged, and fees charged to both parties. Trades are immutable records of executed transactions.

Fee​

A percentage charged on each trade to both the buyer and seller. The default trading fee is 2% of the trade value (shares * price). Fees are recorded on each trade as buyerFee and sellerFee.

Transaction ID​

An optional operator-provided string attached to an order. Can be used as an idempotency key or a reference to the operator's internal transaction system. The prediction engine stores this value but does not enforce uniqueness.

Order Book Concepts​

Order Book​

The collection of all open (unmatched) buy and sell orders for a specific outcome. The order book is organized by price level and determines how new orders are matched.

Bid​

A buy order in the order book. Bids are sorted from highest price to lowest. The highest bid represents the most a buyer is willing to pay.

Ask​

A sell order in the order book. Asks are sorted from lowest price to highest. The lowest ask represents the least a seller is willing to accept.

Best Bid​

The highest price that any buyer is currently willing to pay. This is the top of the bid side of the order book.

Best Ask​

The lowest price that any seller is currently willing to accept. This is the top of the ask side of the order book.

Mid Price​

The midpoint between the best bid and best ask: (bestBid + bestAsk) / 2. Often used as the "current price" of an outcome.

Price Level​

A row in the order book showing the aggregate shares and order count at a specific price. For example, a price level might show 500 shares across 8 orders at a price of 0.65.

Depth​

The number of price levels visible in the order book. Requesting a depth of 10 returns the top 10 bid levels and top 10 ask levels.

Liquidity​

The availability of orders in the book. A market with many orders at tight spreads is considered liquid. Low liquidity means market orders may not fill completely or may execute at unfavorable prices.

Position & Settlement Concepts​

Position​

An aggregate record of an operator's share holdings for a specific outcome in a specific market. Positions are automatically created and updated as trades execute. A position tracks: total shares held, average acquisition price, total cost basis, and realized profit/loss.

Average Price (avgPrice)​

The volume-weighted average price at which shares in a position were acquired. Updated each time a BUY trade adds shares to the position.

Total Cost​

The total amount spent to acquire the shares in a position: shares * avgPrice.

Realized PnL (Profit and Loss)​

The cumulative profit or loss from shares that have been sold. When you sell shares, the difference between the sell price and the average acquisition price is recorded as realized PnL. Unrealized PnL (from shares still held) is not tracked directly — calculate it as shares * (currentPrice - avgPrice).

Settlement​

The process of calculating and recording payouts after a market is resolved. Each position receives a settlement record indicating the payout amount. Winning positions pay out at $1.00 per share; losing positions pay $0.00.

Payout​

The amount owed to a position holder after settlement. Calculated as shares * payoutPerShare. For a winning outcome, payoutPerShare = 1.00. For a losing outcome, payoutPerShare = 0.00.

Market Lifecycle​

Draft​

The initial status of a newly created market. The market is not visible to traders and cannot accept orders.

Upcoming​

A market that has been opened but whose tradingStartsAt time has not yet arrived. The market is visible but not yet tradeable.

Open​

The market is actively accepting orders. This is the only status where trading can occur.

Suspended​

Trading is temporarily paused (e.g., due to a dispute or irregular activity). The market can be resumed to return to the OPEN status.

Closed​

Trading has permanently ended. The market is awaiting resolution (declaration of the winning outcome).

Resolved​

The winning outcome has been declared. The market is ready for settlement.

Settled​

All positions have been settled and payout amounts recorded. This is the terminal state for a successfully completed market.

Cancelled​

The market has been cancelled. All open orders are automatically cancelled. This is a terminal state.

Order Statuses​

Pending​

The order has been placed in the order book and is waiting to be matched. No shares have been filled yet.

Partial (Partially Filled)​

Some of the order's shares have been matched and traded, but the remaining shares are still in the order book awaiting further matches.

Filled​

All of the order's shares have been matched. The order is complete.

Cancelled​

The order was cancelled by the operator before being fully filled. Any remaining unmatched shares are removed from the order book.

Expired​

The order passed its expiresAt time without being fully filled. Remaining shares are removed from the order book.

Rejected​

The order was rejected by the system, typically because a market order could not find any matching liquidity.

Authentication Concepts​

API Key​

A unique secret string assigned to each operator. Used for authenticating all API calls via the X-Api-Key HTTP header. Keep this value secure — if compromised, contact a platform administrator to regenerate it.

Infrastructure Concepts​

Category​

A grouping mechanism for markets. Categories have a name, slug, and optional icon. Markets can be assigned to a category for organization and filtering. Categories can be operator-specific or global (shared across operators).

Cursor-Based Pagination​

A pagination strategy used throughout the API. Instead of page numbers, the API returns a nextCursor value that you pass in subsequent requests to fetch the next page. This is more efficient for large datasets and handles insertions/deletions between pages.

Volume​

The total number of shares traded in a market across all outcomes. Markets track both all-time volume (totalVolume) and 24-hour rolling volume (volume24h).

Audit Log​

An internal record of all significant actions taken on markets (creation, opening, resolution, etc.). Each log entry records the action type, actor, and before/after state.

Event Delivery Concepts​

Webhook​

An HTTP POST notification sent from the prediction engine to an operator-registered URL when an event occurs. Webhooks are signed with HMAC-SHA256 for authenticity. They are the recommended approach for backend-to-backend event delivery. Operators can filter which event types they receive.

Webhook Secret​

A 64-character hex string generated when a webhook is created. Used to compute the HMAC-SHA256 signature of each delivery payload. The secret is only shown in full once — at creation time. Store it securely.

Webhook Signature​

An HMAC-SHA256 hash of the webhook payload body, sent in the X-Webhook-Signature header as sha256=<hex>. Operators should verify this signature before processing webhook deliveries to ensure the payload hasn't been tampered with.

Event Log​

A Postgres-backed log of all events with monotonically increasing sequence numbers. Events are scoped to each operator and retained for 24 hours. The event log powers the Event Replay API.

Sequence Number​

An auto-incrementing integer assigned to each event in the event log. Sequence numbers are unique and strictly increasing, allowing operators to track their read position and replay missed events by requesting events where sequence > lastProcessedSequence.

Event Replay​

The ability to fetch historical events via the REST API (GET /api/v1/events). Used to recover from webhook downtime, WebSocket disconnections, or any missed events. Events can be filtered by type, market, and sequence number.

Event Type​

A classification of events emitted by the prediction engine. Types include: MARKET_CREATED, MARKET_STATUS_CHANGED, MARKET_RESOLVED, ORDER_BOOK_UPDATE, PRICE_UPDATED, ORDER_PLACED, ORDER_MATCHED, ORDER_CANCELLED, POSITION_UPDATED, SETTLEMENT_COMPLETED.

Event Retention​

The duration for which events are stored in the event log. The default retention period is 24 hours. After expiry, events are automatically cleaned up and can no longer be replayed.