How to Build a Prediction Market App on Solana

# Get available prediction events
curl -X GET "https://api.jup.ag/prediction/v1/events?category=crypto" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch(
  'https://api.jup.ag/prediction/v1/events/search?query=bitcoin&limit=10',
  {
    headers: { 'x-api-key': 'YOUR_API_KEY' }
  }
);
const { data: events } = await response.json();

const response = await fetch(
  `https://api.jup.ag/prediction/v1/positions?ownerPubkey=${userPubkey}`,
  {
    headers: { 'x-api-key': 'YOUR_API_KEY' }
  }
);
const { data: positions } = await response.json();

positions.forEach(pos => {
  const side = pos.isYes ? 'YES' : 'NO';
  const pnl = pos.pnlUsd ? (parseInt(pos.pnlUsd) / 1_000_000).toFixed(2) : 'N/A';
  console.log(`${pos.marketMetadata.title}: ${pos.contracts} ${side} contracts, P&L: $${pnl}`);
});

// Check if position is claimable
if (position.claimable) {
  const response = await fetch(
    `https://api.jup.ag/prediction/v1/positions/${position.pubkey}/claim`,
    {
      method: 'POST',
      headers: {
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        ownerPubkey: userPubkey
      })
    }
  );

  const claimResponse = await response.json();

  // Deserialize, sign, and send
  const transaction = VersionedTransaction.deserialize(
    Buffer.from(claimResponse.transaction, 'base64')
  );
  transaction.sign([userWallet]);

  const signature = await connection.sendRawTransaction(transaction.serialize(), {
    skipPreflight: true,
  });
}

interface Event {
  eventId: string;
  isActive: boolean;                       // Whether the event is listed
  isLive: boolean;                         // Whether the event is currently live
  category: 'crypto' | 'sports' | 'politics' | 'esports' | 'culture' | 'economics' | 'tech';
  subcategory: string;                     // Subcategory within the category
  tags: string[];                          // Tags associated with the event
  metadata: {
    eventId: string;
    title: string;
    subtitle: string;
    slug: string;                          // URL-friendly identifier
    series: string;                        // Groups related events (e.g., "NFL Week 1")
    closeTime: string;                     // ISO 8601 formatted close time
    imageUrl: string;
    isLive: boolean;
  };
  markets: Market[];
  volumeUsd: string;                       // Total volume (micro USD)
  closeCondition: string;
  beginAt: string | null;                  // When the event begins
  rulesPdf: string;                        // URL to full rules document
}

interface Market {
  marketId: string;
  status: 'open' | 'closed' | 'cancelled';
  result: null | 'yes' | 'no';
  openTime: number;                          // Unix timestamp
  closeTime: number;                         // Unix timestamp
  resolveAt: number | null;                  // Unix timestamp when market resolved
  marketResultPubkey: string | null;         // Market result account public key
  imageUrl: string;                          // Market image URL
  metadata: {
    title: string;
    status: string;
    openTime: number;
    closeTime: number;
    isTeamMarket: boolean;                   // Whether this is a team market
    rulesPrimary: string;
    rulesSecondary: string;
  };
  pricing: {
    buyYesPriceUsd: number | null;           // Price to buy YES (micro USD)
    buyNoPriceUsd: number | null;            // Price to buy NO (micro USD)
    sellYesPriceUsd: number | null;          // Price to sell YES (micro USD)
    sellNoPriceUsd: number | null;           // Price to sell NO (micro USD)
    volume: number;                          // Trading volume for this market
  };
}

interface Position {
  pubkey: string;                            // Position account
  ownerPubkey: string;                       // User's wallet
  marketId: string;
  isYes: boolean;                            // YES or NO side
  contracts: string;                         // Contracts held (u64 as string)
  avgPriceUsd: string;                       // Average entry price (micro USD)
  totalCostUsd: string;                      // Cost basis (micro USD)
  sizeUsd: string;                           // Alias of totalCostUsd (micro USD)
  valueUsd: string | null;                   // Mark-to-market value (null if market closed)
  markPriceUsd: string | null;               // Current mark price (null if market closed)
  sellPriceUsd: string | null;               // Best exit price (null if unavailable)
  pnlUsd: string | null;                     // Unrealized P&L (micro USD)
  pnlUsdPercent: number | null;
  pnlUsdAfterFees: string | null;            // P&L after fees (micro USD)
  pnlUsdAfterFeesPercent: number | null;
  realizedPnlUsd: number;                    // Realized P&L (micro USD)
  feesPaidUsd: string;                       // Total fees paid (micro USD)
  payoutUsd: string;                         // Payout if position wins (contracts x $1)
  claimable: boolean;                        // Can claim payout?
  claimed: boolean;                          // Has payout been claimed?
  claimedUsd: string;                        // Amount claimed (micro USD)
  openOrders: number;                        // Number of open orders
  openedAt: number;                          // Unix timestamp when position opened
  updatedAt: number;                         // Unix timestamp of last update
  claimableAt: number | null;                // When position becomes claimable
  settlementDate: number | null;             // When market settles
  eventMetadata: EventMetadata;
  marketMetadata: MarketMetadata;
}

interface CreateOrderResponse {
  transaction: string;  // Base64 encoded unsigned transaction
  txMeta: {
    blockhash: string;
    lastValidBlockHeight: number;
  };
  order: {
    orderPubkey: string;
    positionPubkey: string;
    contracts: string;
    orderCostUsd: string;
    estimatedTotalFeeUsd: string;
  };
}

interface HistoryEvent {
  id: number;                                // Unique event identifier
  eventType: 'order_created' | 'order_filled' | 'order_failed'
    | 'payout_claimed' | 'position_updated' | 'position_lost';
  signature: string;                         // Solana transaction signature
  slot: string;                              // Solana slot number
  timestamp: number;                         // Unix timestamp (seconds)
  orderPubkey: string;                       // Associated order account
  positionPubkey: string;                    // Associated position account
  marketId: string;
  ownerPubkey: string;
  keeperPubkey: string;                      // Keeper that processed the tx
  externalOrderId: string;                   // Client-provided order ID
  orderId: string;                           // Venue order ID
  isBuy: boolean;                            // Buy or sell
  isYes: boolean;                            // YES or NO side
  contracts: string;                         // Contracts in the order
  filledContracts: string;                   // Contracts filled
  contractsSettled: string;                  // Contracts settled
  avgFillPriceUsd: string;                   // Average fill price (micro USD)
  maxFillPriceUsd: string;                   // Max fill price (micro USD)
  maxBuyPriceUsd: string | null;             // Buyer max price (micro USD)
  minSellPriceUsd: string | null;            // Seller min price (micro USD)
  depositAmountUsd: string;                  // Deposit amount (micro USD)
  totalCostUsd: string;                      // Total cost (micro USD)
  feeUsd: string | null;                     // Fee charged (micro USD)
  grossProceedsUsd: string;                  // Gross proceeds (micro USD)
  netProceedsUsd: string;                    // Net proceeds (micro USD)
  transferAmountToken: string | null;        // Token amount transferred
  realizedPnl: string | null;                // Realized P&L (micro USD)
  realizedPnlBeforeFees: string | null;      // Realized P&L before fees (micro USD)
  payoutAmountUsd: string;                   // Payout amount (micro USD)
  eventId: string;
  marketMetadata: MarketMetadata;
  eventMetadata: EventMetadata;
}