Skip to main content
GET
/
v1
/
markets
{
  "success": true,
  "data": [
    {
      "id": "<string>",
      "event_id": "<string>",
      "platform": "<string>",
      "token_id": "<string>",
      "ticker": "<string>",
      "outcome": "<string>",
      "price": 123,
      "best_bid": 123,
      "best_ask": 123,
      "spread": 123,
      "volume": 123,
      "volume_24h": 123,
      "liquidity": 123,
      "last_updated": "<string>"
    }
  ]
}

​
Get Markets

Retrieve individual markets (outcomes) within events. Markets represent tradable outcomes like “Yes” or “No”.

​
Endpoint

GET https://api.matchr.xyz/v1/markets

​
Query Parameters

​
limit
number
default:"50"
Number of results to return (max: 200)
​
offset
number
default:"0"
Pagination offset
​
event_id
string
Filter markets by parent event ID
​
platform
string
Filter by platform: polymarket, kalshi, or all
​
min_volume
number
Minimum total volume in USD
​
min_liquidity
number
Minimum available liquidity in USD
​
outcome
string
Filter by outcome type: yes, no, or all

​
Example Request

curl -X GET "https://api.matchr.xyz/v1/markets?event_id=evt_123&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

​
success
boolean
Whether the request succeeded
​
data
array
Array of market objects

​
Example Response

{
  "success": true,
  "data": [
    {
      "id": "mkt_yes123",
      "event_id": "evt_123abc",
      "platform": "polymarket",
      "token_id": "21742633143463906290569050155826241533067272736897614950488156847949938836455",
      "outcome": "Yes",
      "price": 0.52,
      "best_bid": 0.51,
      "best_ask": 0.53,
      "spread": 0.02,
      "volume": 8500000,
      "volume_24h": 250000,
      "liquidity": 150000,
      "last_updated": "2024-10-15T14:30:00Z"
    },
    {
      "id": "mkt_no123",
      "event_id": "evt_123abc",
      "platform": "polymarket",
      "token_id": "48331043336612883890938759509493159234755048973500640163166885851047098274915",
      "outcome": "No",
      "price": 0.48,
      "best_bid": 0.47,
      "best_ask": 0.49,
      "spread": 0.02,
      "volume": 7500000,
      "volume_24h": 200000,
      "liquidity": 120000,
      "last_updated": "2024-10-15T14:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 2
  }
}

​
Get Single Market

Retrieve a specific market by ID. 
GET https://api.matchr.xyz/v1/markets/{market_id}

curl -X GET "https://api.matchr.xyz/v1/markets/mkt_yes123" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Market Orderbook

Get the full orderbook for a market. 
GET https://api.matchr.xyz/v1/markets/{market_id}/orderbook

​
Query Parameters

​
depth
number
default:"10"
Number of price levels to return

​
Response

{
  "success": true,
  "data": {
    "market_id": "mkt_yes123",
    "timestamp": "2024-10-15T14:30:00Z",
    "bids": [
      { "price": 0.51, "size": 5000 },
      { "price": 0.50, "size": 12000 },
      { "price": 0.49, "size": 8000 }
    ],
    "asks": [
      { "price": 0.53, "size": 4000 },
      { "price": 0.54, "size": 9000 },
      { "price": 0.55, "size": 15000 }
    ]
  }
}

​
Error Codes

CodeDescription
400Invalid query parameters
401Missing or invalid API key
404Market not found
429Rate limit exceeded
500Server error