Prediction Markets API

Prediction markets enable users to bet on future outcomes by purchasing and trading shares. Markets use automated market makers for price discovery and liquidity. Amounts are in wei.

Base URL (staging): https://mcap-api-564778804231.us-east4.run.app

Overview

The Prediction Markets API is organized into three categories based on authentication requirements:

Public Endpoints: No authentication required - used for browsing markets and getting public data
User Endpoints: JWT authentication required - used for placing bets, managing positions, and claiming payouts
Provider Endpoints: API key authentication required - used by providers to create and manage markets

Public Endpoints

These endpoints are publicly accessible and require no authentication.

Search Markets

POST /v1/markets/search

Request:

{
  "filters": {
    "provider_id": "provider-123",
    "token_id": "token-456",
    "status": "active",
    "category": "sports",
    "search_query": "NFL Championship"
  },
  "pagination": {
    "page": 1,
    "per_page": 20
  },
  "sort": {
    "field": "created_at",
    "direction": "desc"
  }
}

Response 200:

{
  "data": [
    {
      "id": "market-123",
      "question": "Who will win the 2024 NFL Championship?",
      "description": "Prediction market for the 2024 NFL Championship winner",
      "category": "sports",
      "status": "active",
      "total_pool": "50000000000000000000",
      "total_volume": "25000000000000000000",
      "outcomes": [
        {
          "id": "outcome-1",
          "title": "Kansas City Chiefs",
          "current_price": "0.35",
          "total_shares": "14285714285714285714"
        }
      ],
      "token": {
        "id": "token-456",
        "symbol": "USDC",
        "name": "USD Coin"
      },
      "provider": {
        "id": "provider-123", 
        "name": "SportsBet Pro"
      },
      "created_at": "2024-01-15T10:00:00Z",
      "closes_at": "2024-02-11T23:59:59Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 45,
    "total_pages": 3
  }
}

Get Market Details

GET /v1/markets/{market_id}

Response 200:

{
  "id": "market-123",
  "question": "Who will win the 2024 NFL Championship?",
  "description": "Prediction market for the 2024 NFL Championship winner",
  "category": "sports",
  "status": "active",
  "total_pool": "50000000000000000000",
  "total_volume": "25000000000000000000",
  "outcomes": [
    {
      "id": "outcome-1",
      "title": "Kansas City Chiefs", 
      "current_price": "0.35",
      "total_shares": "14285714285714285714",
      "total_volume": "8750000000000000000"
    },
    {
      "id": "outcome-2",
      "title": "Buffalo Bills",
      "current_price": "0.28", 
      "total_shares": "17857142857142857142",
      "total_volume": "7000000000000000000"
    }
  ],
  "token": {
    "id": "token-456",
    "symbol": "USDC",
    "name": "USD Coin",
    "decimals": 18
  },
  "provider": {
    "id": "provider-123",
    "name": "SportsBet Pro"
  },
  "created_at": "2024-01-15T10:00:00Z",
  "closes_at": "2024-02-11T23:59:59Z",
  "resolution_source": "Official NFL records",
  "minimum_bet": "1000000000000000000"
}

Preview Bet

POST /v1/markets/bet-preview

Request:

{
  "outcome_id": "outcome-1",
  "amount": "10000000000000000000"
}

Response 200:

{
  "outcome_id": "outcome-1",
  "amount": "10000000000000000000",
  "estimated_shares": "27027027027027027027",
  "average_price": "0.37",
  "price_impact": "0.02",
  "new_outcome_price": "0.37",
  "market_id": "market-123",
  "token": {
    "id": "token-456",
    "symbol": "USDC", 
    "decimals": 18
  }
}

Preview Sell

POST /v1/markets/sell-preview

Request (by share amount):

{
  "outcome_id": "outcome-1",
  "shares_amount": "10000000000000000000"
}

Request (by target proceeds):

{
  "outcome_id": "outcome-1",
  "target_proceeds": "9500000000000000000"
}

Response 200:

{
  "outcome_id": "outcome-1",
  "estimated_shares": "10000000000000000000",
  "estimated_proceeds": "9230769230769230769",
  "average_price": "0.923",
  "price_impact": "-0.015",
  "new_outcome_price": "0.335",
  "market_id": "market-123",
  "token": {
    "id": "token-456",
    "symbol": "USDC",
    "decimals": 18
  }
}

Search Market Positions

POST /v1/markets/positions/search

Request:

{
  "filters": {
    "market_id": "market-123",
    "outcome_id": "outcome-1",
    "wallet_address": "0x1234567890abcdef1234567890abcdef12345678",
    "transaction_type": "buy",
    "from_date": "2024-01-01T00:00:00Z",
    "to_date": "2024-01-31T23:59:59Z"
  },
  "pagination": {
    "page": 1,
    "per_page": 50
  },
  "sort": {
    "field": "created_at",
    "direction": "desc"
  }
}

Response 200:

{
  "data": [
    {
      "id": "transaction-789",
      "market_id": "market-123",
      "outcome_id": "outcome-1",
      "wallet_id": "wallet-456",
      "wallet_address": "0x1234567890abcdef1234567890abcdef12345678",
      "transaction_type": "buy",
      "amount": "10000000000000000000",
      "shares": "27027027027027027027",
      "price": "0.37",
      "created_at": "2024-01-20T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 234,
    "total_pages": 5
  }
}

Search Price History

POST /v1/markets/price-history/search

Request:

{
  "filters": {
    "market_id": "market-123",
    "outcome_id": "outcome-1",
    "from_date": "2024-01-01T00:00:00Z",
    "to_date": "2024-01-31T23:59:59Z",
    "interval": "1h"
  },
  "pagination": {
    "page": 1,
    "per_page": 100
  },
  "sort": {
    "field": "timestamp",
    "direction": "asc"
  }
}

Response 200:

{
  "data": [
    {
      "market_id": "market-123",
      "outcome_id": "outcome-1",
      "price": "0.32",
      "volume": "5000000000000000000",
      "timestamp": "2024-01-20T14:00:00Z"
    },
    {
      "market_id": "market-123",
      "outcome_id": "outcome-1", 
      "price": "0.35",
      "volume": "3000000000000000000",
      "timestamp": "2024-01-20T15:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 100,
    "total": 720,
    "total_pages": 8
  }
}

User Endpoints

These endpoints require JWT authentication obtained through wallet signature login.

Place Bet

POST /v1/markets/{market_id}/bet
Authorization: Bearer <jwt>

Request:

{
  "session_id": "session-789",
  "outcome_id": "outcome-1",
  "amount": "10000000000000000000"
}

Response 200:

{
  "bet_id": "bet-456",
  "market_id": "market-123",
  "outcome_id": "outcome-1",
  "session_id": "session-789",
  "amount": "10000000000000000000",
  "shares_purchased": "27027027027027027027",
  "average_price": "0.37",
  "transaction_fee": "50000000000000000",
  "net_amount": "9950000000000000000",
  "balance_before": "100000000000000000000",
  "balance_after": "90050000000000000000",
  "created_at": "2024-01-20T14:30:00Z",
  "status": "confirmed"
}

Sell Shares

POST /v1/markets/{market_id}/sell
Authorization: Bearer <jwt>

Request (by share amount):

{
  "session_id": "session-789",
  "outcome_id": "outcome-1", 
  "shares_amount": "10000000000000000000"
}

Request (by target proceeds):

{
  "session_id": "session-789",
  "outcome_id": "outcome-1",
  "target_proceeds": "9500000000000000000"
}

Response 200:

{
  "transaction_id": "txn-789",
  "market_id": "market-123",
  "outcome_id": "outcome-1", 
  "session_id": "session-789",
  "shares_sold": "10000000000000000000",
  "proceeds": "9230769230769230769",
  "average_price": "0.923",
  "transaction_fee": "46153846153846153",
  "net_proceeds": "9184615384615384616",
  "balance_before": "90050000000000000000",
  "balance_after": "99234615384615384616",
  "created_at": "2024-01-20T15:45:00Z",
  "status": "confirmed"
}

Search User Positions

POST /v1/markets/holdings/search
Authorization: Bearer <jwt>

Request:

{
  "filters": {
    "market_id": "market-123",
    "outcome_id": "outcome-1",
    "status": "active",
    "position_type": "long"
  },
  "pagination": {
    "page": 1,
    "per_page": 20
  },
  "sort": {
    "field": "current_value",
    "direction": "desc"
  }
}

Response 200:

{
  "data": [
    {
      "id": "position-123",
      "market_id": "market-123",
      "outcome_id": "outcome-1", 
      "wallet_id": "wallet-456",
      "shares": "17027027027027027027",
      "average_cost": "0.37",
      "total_invested": "6300000000000000000",
      "current_price": "0.35",
      "current_value": "5959459459459459459",
      "unrealized_pnl": "-340540540540540541",
      "status": "active",
      "position_type": "long",
      "is_claimable": false,
      "created_at": "2024-01-20T14:30:00Z",
      "updated_at": "2024-01-20T15:45:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 8,
    "total_pages": 1
  }
}

Claim Payout

POST /v1/markets/positions/{position_id}/claim
Authorization: Bearer <jwt>

Request:

{
  "session_id": "session-789"
}

Response 200:

{
  "claim_id": "claim-456",
  "position_id": "position-123",
  "market_id": "market-123",
  "outcome_id": "outcome-1",
  "session_id": "session-789",
  "shares_claimed": "17027027027027027027",
  "claimed_amount": "17027027027027027027",
  "payout_ratio": "1.0",
  "balance_before": "99234615384615384616",
  "balance_after": "116261642411642411643",
  "claimed_at": "2024-02-12T10:00:00Z",
  "status": "completed"
}

Provider Endpoints

These endpoints require API key authentication and are used by providers to create and manage prediction markets.

Resolve Market

POST /v1/providers/markets/{market_id}/resolve
Authorization: Bearer <api_key>

Request:

{
  "winning_outcome_id": "outcome-1",
  "resolver_wallet_id": "wallet-resolver-123",
  "resolution_source": "Official NFL Records",
  "resolution_data": {
    "final_score": "Chiefs 28 - Bills 21",
    "game_date": "2024-02-11",
    "verified_by": "NFL Commissioner"
  }
}

Response 200:

{
  "market_id": "market-123",
  "winning_outcome_id": "outcome-1",
  "resolved_at": "2024-02-12T09:00:00Z",
  "total_pool": "50000000000000000000",
  "winning_pool": "17500000000000000000",
  "payout_ratio": "2.857142857142857143",
  "positions_updated": 234,
  "resolution_source": "Official NFL Records",
  "resolver_wallet_id": "wallet-resolver-123",
  "status": "resolved"
}

Create Market

POST /v1/providers/markets
Authorization: Bearer <api_key>

Request:

{
  "game_id": "game-456",
  "question": "Who will win the 2024 NFL Championship?",
  "description": "Prediction market for the 2024 NFL Championship winner",
  "tags": ["sports", "nfl", "championship"],
  "images": {
    "banner": "https://example.com/banner.jpg",
    "thumbnail": "https://example.com/thumb.jpg"
  },
  "pricing_method": "lmsr",
  "token_id": "token-456",
  "min_bet_amount": "1000000000000000000",
  "max_bet_amount": "100000000000000000000",
  "liquidity": "10000000000000000000",
  "starts_at": "2024-01-15T10:00:00Z",
  "ends_at": "2024-02-11T23:59:59Z",
  "creator_wallet_id": "wallet-creator-123",
  "creator_fee_percentage": 2.5,
  "platform_fee_percentage": 1.0,
  "metadata": {
    "resolution_source": "Official NFL records",
    "category": "sports"
  },
  "outcomes": [
    {
      "title": "Kansas City Chiefs",
      "description": "Kansas City Chiefs win the championship",
      "outcome_index": 0
    },
    {
      "title": "Buffalo Bills", 
      "description": "Buffalo Bills win the championship",
      "outcome_index": 1
    }
  ]
}

Response 201:

{
  "market": {
    "id": "market-123",
    "question": "Who will win the 2024 NFL Championship?",
    "description": "Prediction market for the 2024 NFL Championship winner",
    "status": "active",
    "created_at": "2024-01-15T10:00:00Z",
    "starts_at": "2024-01-15T10:00:00Z",
    "ends_at": "2024-02-11T23:59:59Z"
  },
  "outcomes": [
    {
      "id": "outcome-1",
      "title": "Kansas City Chiefs",
      "current_price": "0.50",
      "total_shares": "0"
    },
    {
      "id": "outcome-2",
      "title": "Buffalo Bills",
      "current_price": "0.50", 
      "total_shares": "0"
    }
  ],
  "message": "Market created successfully"
}

Update Market

PUT /v1/providers/markets/{market_id}
Authorization: Bearer <api_key>

Request:

{
  "question": "Updated: Who will win the 2024 NFL Championship?",
  "description": "Updated prediction market description",
  "tags": ["sports", "nfl", "championship", "updated"],
  "min_bet_amount": "2000000000000000000",
  "ends_at": "2024-02-12T23:59:59Z",
  "creator_fee_percentage": 3.0,
  "metadata": {
    "resolution_source": "Updated: Official NFL records",
    "category": "sports",
    "updated": true
  }
}

Response 200:

{
  "market": {
    "id": "market-123",
    "question": "Updated: Who will win the 2024 NFL Championship?",
    "description": "Updated prediction market description",
    "status": "active",
    "updated_at": "2024-01-16T14:30:00Z"
  },
  "message": "Market updated successfully"
}

Create Outcome

POST /v1/providers/markets/{market_id}/outcomes
Authorization: Bearer <api_key>

Request:

{
  "title": "Philadelphia Eagles",
  "description": "Philadelphia Eagles win the championship",
  "images": {
    "logo": "https://example.com/eagles-logo.png"
  },
  "outcome_index": 2
}

Response 201:

{
  "outcome": {
    "id": "outcome-3",
    "title": "Philadelphia Eagles",
    "description": "Philadelphia Eagles win the championship",
    "current_price": "0.33",
    "total_shares": "0",
    "outcome_index": 2
  },
  "message": "Outcome created successfully"
}

Update Outcome

PUT /v1/providers/markets/{market_id}/outcomes/{outcome_id}
Authorization: Bearer <api_key>

Request:

{
  "title": "Updated: Philadelphia Eagles",
  "description": "Updated: Philadelphia Eagles win the championship",
  "images": {
    "logo": "https://example.com/eagles-logo-updated.png",
    "banner": "https://example.com/eagles-banner.jpg"
  },
  "outcome_index": 3
}

Response 200:

{
  "outcome": {
    "id": "outcome-3",
    "title": "Updated: Philadelphia Eagles",
    "description": "Updated: Philadelphia Eagles win the championship",
    "current_price": "0.33",
    "total_shares": "0",
    "outcome_index": 3
  },
  "message": "Outcome updated successfully"
}

Cancel Market

POST /v1/providers/markets/{market_id}/cancel
Authorization: Bearer <api_key>

Request:

{
  "canceller_wallet_id": "wallet-admin-456",
  "cancellation_source": "Administrative Decision",
  "reason": "Event cancelled due to unforeseen circumstances",
  "cancellation_data": {
    "original_event_date": "2024-02-11",
    "cancellation_reason": "Stadium closure due to severe weather",
    "approved_by": "Sports Commissioner"
  }
}

Response 200:

{
  "market_id": "market-123",
  "cancelled_at": "2024-02-10T16:00:00Z",
  "total_refund_amount": "45000000000000000000",
  "positions_refunded": 187,
  "user_refunds": [
    {
      "wallet_id": "wallet-456",
      "refund_amount": "10000000000000000000",
      "original_positions": 3
    }
  ],
  "cancellation_source": "Administrative Decision",
  "reason": "Event cancelled due to unforeseen circumstances",
  "cancellation_data": {
    "original_event_date": "2024-02-11",
    "cancellation_reason": "Stadium closure due to severe weather", 
    "approved_by": "Sports Commissioner"
  },
  "status": "cancelled"
}

Overview​

Public Endpoints​

Search Markets​

Get Market Details​

Preview Bet​

Preview Sell​

Search Market Positions​

Search Price History​

User Endpoints​

Place Bet​

Sell Shares​

Search User Positions​

Claim Payout​

Provider Endpoints​

Resolve Market​

Create Market​

Update Market​

Create Outcome​

Update Outcome​

Cancel Market​

Overview

Public Endpoints

Search Markets

Get Market Details

Preview Bet

Preview Sell

Search Market Positions

Search Price History

User Endpoints

Place Bet

Sell Shares

Search User Positions

Claim Payout

Provider Endpoints

Resolve Market

Create Market

Update Market

Create Outcome

Update Outcome

Cancel Market