Query whale events
MCP tool: query_whale_events
Returns the matching trades themselves, most recent first, for inspecting specifics rather than aggregates. Prefer backtest when you want a score; this returns rows and is slower.
POST rather than GET because criteria are a nested object and encoding that into a query string is worse for everyone. An empty body is valid and returns the most recent trades across the whole feed.
Body parameters
criteriaobjectOptional rule to filter by. Omit for all trades.
platformsstring[]Venues to include: "polymarket", "kalshi". Omit for both, which is usually right.
categoriesstring[]Market categories: "sports", "politics", "crypto", "finance", "culture". Omit for all.
sportsLeaguesstring[]Leagues, e.g. ["NBA", "NFL"]. Only applies to sports markets. Max 20.
minAmountUsdnumberMinimum trade size in USD. Typical values are 10000 to 50000.
maxAmountUsdnumberMaximum trade size in USD. Must be at least minAmountUsd when both are set.
priceMinnumberMinimum entry price, 0 to 1. 0.75 and up is heavy favourites.
priceMaxnumberMaximum entry price, 0 to 1. 0.20 and below is longshots. Must be at least priceMin when both are set.
eventTypesstring[]How the trade changed the trader's position: "open", "add", "flip", "trim", "close", "unknown". Entries only is ["open", "add", "flip"], which is the usual choice. Trims and closes are exits and never settle, so they cannot be scored.
directionsstring[]Trade direction: "buy_yes", "buy_no", "sell_yes", "sell_no". Only buys are ever scored; sells never resolve.
keywordsstring[]Case-insensitive substrings matched against the market name. Any one matching is enough. Max 10.
sinceDaysintegerdefault: 90Lookback window in days, 1 to 365.
limitintegerdefault: 50Rows to return, 1 to 200.
offsetintegerdefault: 0Rows to skip, for paging.
Response
resolution is null while the market is open, then "win", "loss", or "void". Voids have zero PnL and are excluded from win rate and return.
curl -X POST https://api.rivo.markets/v1/events \
-H "Authorization: Bearer rivo_live_..." \
-H "Content-Type: application/json" \
-d '{
"criteria": {
"categories": [
"politics"
],
"minAmountUsd": 25000
},
"limit": 2
}'import requests
r = requests.post(
"https://api.rivo.markets/v1/events",
headers={"Authorization": "Bearer rivo_live_..."},
json={
"criteria": {
"categories": ["politics"],
"minAmountUsd": 25000,
},
"limit": 2,
},
)
print(r.json()["data"])const res = await fetch("https://api.rivo.markets/v1/events", {
method: "POST",
headers: {
Authorization: "Bearer rivo_live_...",
"Content-Type": "application/json",
},
body: JSON.stringify({
criteria: {
categories: ["politics"],
minAmountUsd: 25000,
},
limit: 2,
}),
});
const { data } = await res.json();{
"success": true,
"data": {
"events": [
{
"id": "pm-9c1e...",
"platform": "polymarket",
"platformMarketId": "0x8a41...",
"marketTitle": "Democratic presidential nominee 2028",
"marketCategory": "politics",
"direction": "buy_yes",
"outcomeName": "Gavin Newsom",
"amount": 62000,
"price": 0.31,
"positionDelta": "open",
"detectedAt": "2026-08-13T06:41:22.000Z",
"resolution": null,
"pnlUsd": null
}
],
"limit": 2,
"offset": 0
}
}