Limit:    60 requests per minute per IP
Headers:  X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Status:   429 Too Many Requests (when exceeded)

// Request
fetch('/api/markets')

// Response
{
  "markets": {
    "1": {
      "market": {
        "id": "1",
        "collateral": "0x3c499c...",
        "ctf": "0x4D97DC...",
        "yesPositionId": "67526...",
        "noPositionId": "65657...",
        "active": true,
        "resolved": false,
        "winningOutcome": 0
      },
      "orderBooks": {
        "0": {  // YES position
          "bids": [{ "price": "4500", "depth": "1000000000" }],
          "asks": [{ "price": "5500", "depth": "500000000" }]
        },
        "1": {  // NO position
          "bids": [...],
          "asks": [...]
        }
      },
      "lastUpdated": 1706395200000
    },
    "2": { ... }
  },
  "marketList": [...],      // Market metadata
  "contracts": { ... },     // Contract addresses
  "chainId": 137,
  "feeBps": 100,
  "preloadComplete": true,
  "cachedCount": 20,
  "totalCount": 20
}

// Request
fetch('/api/market?id=1')

// Response
{
  "market": { ... },
  "orderBooks": { ... },
  "lastUpdated": 1706395200000
}

// Request
fetch('/api/fee')

// Response
{ "feeBps": 100 }  // 100 bps = 1%

// All markets, last 24 hours (default)
fetch('/api/price-history')

// Specific market
fetch('/api/price-history?market=1')

// Last 6 hours
fetch('/api/price-history?hours=6')

// Response
{
  "snapshots": [
    {
      "timestamp": 1706395200000,
      "isoTime": "2026-01-27T12:00:00.000Z",
      "yes": {
        "bestBid": 0.45,
        "bestAsk": 0.55,
        "midPrice": 0.50,
        "spread": 0.10,
        "bidDepth": 1000.50,   // USD
        "askDepth": 500.25,
        "bidLevels": 5,
        "askLevels": 3
      },
      "no": { ... }
    },
    ...
  ],
  "totalSnapshots": 288,
  "oldestSnapshot": "2026-01-26T12:00:00.000Z",
  "newestSnapshot": "2026-01-27T12:00:00.000Z"
}

// Fetch all markets
async function getAllMarkets() {
  const resp = await fetch('/api/markets');
  if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
  return resp.json();
}

// Get best prices for a market
async function getBestPrices(marketId) {
  const data = await getAllMarkets();
  const market = data.markets[marketId];
  if (!market) return null;
  
  const yesBids = market.orderBooks[0].bids;
  const yesAsks = market.orderBooks[0].asks;
  
  return {
    yesBestBid: yesBids[0] ? Number(yesBids[0].price) / 10000 : null,
    yesBestAsk: yesAsks[0] ? Number(yesAsks[0].price) / 10000 : null,
  };
}

// Handle rate limiting
async function fetchWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const resp = await fetch(url);
    
    if (resp.status === 429) {
      const data = await resp.json();
      const waitMs = (data.retryAfter || 60) * 1000;
      console.log(`Rate limited, waiting ${waitMs}ms`);
      await new Promise(r => setTimeout(r, waitMs));
      continue;
    }
    
    return resp;
  }
  throw new Error('Max retries exceeded');
}

import requests
import time

BASE_URL = "https://your-8ball-domain.com"

def get_markets():
    """Fetch all market data."""
    resp = requests.get(f"{BASE_URL}/api/markets")
    resp.raise_for_status()
    return resp.json()

def get_price_history(market_id=None, hours=24):
    """Fetch price history for charts."""
    params = {"hours": hours}
    if market_id:
        params["market"] = market_id
    resp = requests.get(f"{BASE_URL}/api/price-history", params=params)
    resp.raise_for_status()
    return resp.json()

def get_best_prices(market_id):
    """Get current best bid/ask for a market."""
    data = get_markets()
    market = data["markets"].get(str(market_id))
    if not market:
        return None
    
    yes_bids = market["orderBooks"]["0"]["bids"]
    yes_asks = market["orderBooks"]["0"]["asks"]
    
    return {
        "yes_best_bid": int(yes_bids[0]["price"]) / 10000 if yes_bids else None,
        "yes_best_ask": int(yes_asks[0]["price"]) / 10000 if yes_asks else None,
    }

# Example usage
if __name__ == "__main__":
    markets = get_markets()
    print(f"Loaded {markets['cachedCount']} markets")
    
    prices = get_best_prices(1)
    print(f"Market 1 - Bid: {prices['yes_best_bid']}, Ask: {prices['yes_best_ask']}")

// Get the next available market ID (tells you how many markets exist)
const nextId = await registry.nextMarketId();
// If nextId = 21, markets 1-20 exist

// List all markets
for (let id = 1; id < nextId; id++) {
  const market = await registry.get(id);
  console.log(`Market ${id}: ${market.resolutionCriteria}`);
}

const market = await registry.get(marketId);

{
  collateral: address,      // USDC contract address
  ctf: address,             // ConditionalTokens contract
  questionId: bytes32,      // Unique question identifier
  conditionId: bytes32,     // CTF condition ID
  yesIndexSet: uint256,     // Index set for YES outcome
  yesPositionId: uint256,   // ERC-1155 token ID for YES
  noPositionId: uint256,    // ERC-1155 token ID for NO
  oracleAdapter: address,   // Resolution oracle
  resolutionCriteria: string, // Human-readable question
  active: bool,             // Whether trading is enabled
  resolved: bool,           // Whether outcome is known
  winningOutcome: uint8     // 0=YES won, 1=NO won (if resolved)
}

async function findMarketByKeyword(keyword) {
  const nextId = await registry.nextMarketId();
  
  for (let id = 1; id < nextId; id++) {
    const market = await registry.get(id);
    if (market.resolutionCriteria.toLowerCase().includes(keyword.toLowerCase())) {
      return { id, market };
    }
  }
  return null;
}

// Example: Find the Bitcoin market
const btcMarket = await findMarketByKeyword('bitcoin');
console.log(`Bitcoin market ID: ${btcMarket.id}`);
// Output: Bitcoin market ID: 11

// Fetch deployment info
const resp = await fetch('/deployment.json');
const deployment = await resp.json();

// Access markets directly
deployment.markets.forEach(m => {
  const id = m.id || m.marketId;
  console.log(`ID: ${id}, Question: ${m.criteria}`);
  console.log(`  YES token: ${m.yesPositionId}`);
  console.log(`  NO token:  ${m.noPositionId}`);
});

// Example output:
// ID: 1, Question: GOP retains House in 2026?
//   YES token: 4883681747517307224539...
//   NO token:  1934846715766243280345...

// Get user's YES token balance for market 1
const market = await registry.get(1);
const yesBalance = await ctf.balanceOf(userAddress, market.yesPositionId);
const noBalance = await ctf.balanceOf(userAddress, market.noPositionId);

console.log(`YES: ${yesBalance}, NO: ${noBalance}`);

// Parameters
marketId: uint256    // Market ID (1, 2, 3, ...)
position: uint8      // 0 = YES, 1 = NO
side: uint8          // 0 = BID (buy), 1 = ASK (sell)

// Returns array of:
{
  price: uint256,         // Price in 4 decimals (5000 = $0.50)
  totalRemaining: uint256,// Total size at this price
  lastUpdate: uint64,     // Timestamp of last update
  cumShareSeconds: uint256// Cumulative liquidity-time
}

// Example (ethers.js)
const levels = await orderbook.getLevelSnapshots(1, 0, 0);
// Returns all bid levels for YES position in market 1

// Returns
{
  maker: address,
  marketId: uint256,
  price: uint256,        // 4 decimals (1 = 0.0001, 10000 = 1.0)
  remaining: uint256,    // Remaining size
  createdAt: uint64,
  lastUpdate: uint64,
  lockUntil: uint64,     // 0 if not locked
  side: uint8,           // 0 = BID, 1 = ASK
  position: uint8,       // 0 = YES, 1 = NO
  feeBps: uint256,
  active: bool,
  cumShareSeconds: uint256
}

// Example
const order = await orderbook.orders(42);

const prices = await orderbook.getActivePrices(
  marketId,  // uint256
  position,  // 0=YES, 1=NO
  side       // 0=BID, 1=ASK
);
// Returns uint256[] of active price levels

const orderIds = await orderbook.getOrdersAtPrice(
  marketId,  // uint256
  position,  // 0=YES, 1=NO
  side,      // 0=BID, 1=ASK
  price      // uint256, 4 decimals
);

// Paginated version for busy levels
const { orderIds, total } = await orderbook.getOrdersAtPricePaginated(
  marketId, position, side, price,
  offset,  // uint256
  limit    // uint256
);

const [decimals, maxPrice] = await orderbook.priceConfig();
// decimals = 4 (0.0001 precision)
// maxPrice = 10000 (1.0000)

const [locked, lockUntilTimestamp] = await orderbook.getOrderLock(orderId);
// locked: bool - true if block.timestamp < lockUntil
// lockUntilTimestamp: uint64 - unix timestamp when lock expires

// Calculate escrow: notional + fee buffer
// notional = price * size / 1e4 (UNIT)
// fee = notional * feeBps / 10000
const notional = price * size / 10000n;
const fee = notional * 100n / 10000n;  // 100 bps = 1%
const escrow = notional + fee;
await usdc.approve(orderbookAddress, escrow);

// Place bid (buy order)
const tx = await orderbook.placeBid(
  marketId,    // uint256
  price,       // uint256 (4 decimals, e.g. 4500 = $0.45)
  size,        // uint256 (6 decimals, e.g. 100000000 = 100 shares)
  position     // 0 = YES, 1 = NO
);

// With lock (for Valley rewards)
const tx = await orderbook.placeBidWithLock(
  marketId,
  price,
  size,
  position,
  lockSeconds  // Max 1800 (30 minutes)
);

// Approve CTF tokens first
await ctf.setApprovalForAll(orderbookAddress, true);

// Place ask (sell order)
const tx = await orderbook.placeAsk(
  marketId,
  price,       // 4 decimals
  size,
  position     // 0 = YES, 1 = NO
);

// With lock
const tx = await orderbook.placeAskWithLock(
  marketId, price, size, position, lockSeconds
);

// You must own the position tokens to sell
await ctf.setApprovalForAll(orderbookAddress, true);

const tx = await orderbook.fillBid(
  orderId,     // uint64 - the bid order to fill
  size         // uint256 - amount to fill
);

// Calculate cost (notional + fee, taker pays both)
const order = await orderbook.orders(orderId);
const notional = order.price * size / 10000n;
const fee = notional * order.feeBps / 10000n;
await usdc.approve(orderbookAddress, notional + fee);

const tx = await orderbook.fillAsk(
  orderId,     // uint64 - the ask order to fill
  size         // uint256 - amount to fill
);

await orderbook.amendOrder(
  orderId,     // uint64
  newSize      // uint256 - new remaining size
);

// Full cancel (pass the full remaining size)
const order = await orderbook.orders(orderId);
await orderbook.cancelOrder(orderId, order.remaining);

// Partial cancel (must leave remainder >= 10e6 or cancel fully)
await orderbook.cancelOrder(orderId, sizeToCancel);

// Alternative: amendOrder to zero also fully cancels
await orderbook.amendOrder(orderId, 0);

// Cancel ask and send position tokens to a different address
await orderbook.cancelOrderTo(
  orderId,       // uint64
  sizeToCancel,  // uint256
  recipientAddr  // address - receives the position tokens
);

// After a bid is fully filled, rounding dust may remain in escrow
await orderbook.withdrawResidual(orderId);
// Returns any remaining USDC to the maker

// When ask orders are amended down or partially cancelled,
// refundable positions accumulate for pull-withdrawal
await orderbook.withdrawPosition(
  orderId,     // uint64 - must be an inactive ask order you own
  toAddress    // address - receives the position tokens
);

const orderIds = await orderbook.getOrdersByMaker(userAddress);
// Returns uint64[] of all order IDs (active and inactive)

// Paginated version for large order histories
const { orderIds, total } = await orderbook.getOrdersByMakerPaginated(
  userAddress,
  offset,  // uint256 - skip first N
  limit    // uint256 - max to return
);

ORDER_FLOOR = 10_000_000  // 10 shares minimum (6 decimals)
LOCK_CEILING = 1800       // Max lock duration: 30 minutes
FEE_CEILING = 1000        // Max fee: 10% (1000 bps)
PRICE_UNIT = 10000        // 1.0000 in 4-decimal format

// Get market info
const market = await registry.get(marketId);
const ctf = new ethers.Contract(market.ctf, CTF_ABI, signer);
const usdc = new ethers.Contract(market.collateral, ERC20_ABI, signer);

// Amount to mint (in 6 decimals for USDC)
const amount = ethers.parseUnits("100", 6); // 100 USDC

// Approve CTF to spend USDC
await usdc.approve(ctfAddress, amount);

// Split into YES + NO tokens
const partition = [1, 2]; // [YES, NO]
const parentCollectionId = "0x0000000000000000000000000000000000000000000000000000000000000000";

const tx = await ctf.splitPosition(
  market.collateral,    // USDC address
  parentCollectionId,   // bytes32 - always zero for root
  market.conditionId,   // bytes32 - from market struct
  partition,            // uint256[] - [1,2] for YES/NO
  amount                // uint256 - amount in USDC
);
await tx.wait();

// Result: You now have 100 YES tokens + 100 NO tokens

// Amount to merge (must have equal YES and NO)
const amount = ethers.parseUnits("50", 6); // 50 of each

// Merge back into USDC
const tx = await ctf.mergePositions(
  market.collateral,    // USDC address
  parentCollectionId,   // bytes32 - always zero
  market.conditionId,   // bytes32 - from market
  partition,            // [1, 2]
  amount                // amount to merge
);
await tx.wait();

// Result: Burned 50 YES + 50 NO, received 50 USDC

// Check if market is resolved
const [resolved, winningOutcome] = await registry.getResolutionStatus(marketId);
if (!resolved) throw new Error("Market not resolved yet");

// Redeem all positions (CTF calculates payout based on winning outcome)
const indexSets = [1, 2]; // Submit both YES and NO

const tx = await ctf.redeemPositions(
  market.collateral,    // USDC address
  parentCollectionId,   // bytes32 - always zero
  market.conditionId,   // bytes32 - from market
  indexSets             // [1, 2] - redeem both outcomes
);
await tx.wait();

// Result: Winning tokens converted to USDC, losing tokens burned

const ctf = new ethers.Contract(market.ctf, ERC1155_ABI, provider);

// Get position token IDs
const yesPositionId = market.yesPositionId;
const noPositionId = market.noPositionId;

// Check balances
const yesBalance = await ctf.balanceOf(userAddress, yesPositionId);
const noBalance = await ctf.balanceOf(userAddress, noPositionId);

console.log(`YES: ${ethers.formatUnits(yesBalance, 6)}`);
console.log(`NO: ${ethers.formatUnits(noBalance, 6)}`);

const CTF_ABI = [
  "function splitPosition(address collateralToken, bytes32 parentCollectionId, bytes32 conditionId, uint256[] partition, uint256 amount)",
  "function mergePositions(address collateralToken, bytes32 parentCollectionId, bytes32 conditionId, uint256[] partition, uint256 amount)",
  "function redeemPositions(address collateralToken, bytes32 parentCollectionId, bytes32 conditionId, uint256[] indexSets)",
  "function balanceOf(address account, uint256 id) view returns (uint256)",
  "function setApprovalForAll(address operator, bool approved)",
  "function isApprovedForAll(address account, address operator) view returns (bool)"
];