Prediction Market Settlements API
The PredictionSettlements API returns Split, Merge, and Redemption events for prediction markets (e.g. Polymarket) on Polygon. Use it to stream live settlements, list latest activity, count events by type, find large redemptions (whales), and rank top winners or top markets by redeemed amount.
Network: Polygon (network: matic). Part of the Prediction Market API lifecycle (Management → Trades → Settlement).
How to get Polymarket market resolution and settlement data
You get Polymarket market resolution and settlement data from one API: resolution (the final outcome of a market) comes from the PredictionManagements cube, and settlement (redemptions and payouts to the winners) comes from the PredictionSettlements cube, both on EVM(network: matic). Bitquery decodes the Conditional Tokens and adapter events for you, so you do not need to index Polygon logs yourself.
The on-chain terms map to the API like this:
| On-chain term | What it is | Cube | Event type |
|---|---|---|---|
ConditionResolution | The Conditional Tokens contract records the result and the payout vector of a condition. | PredictionManagements | Management.EventType: "Resolved"; the winning outcome is in Prediction.Outcome |
UMA oracle resolution (QuestionResolved) | Polymarket's UMA adapter settles the question and reports the payouts to Conditional Tokens, which emits ConditionResolution in the same transaction. | PredictionManagements | "Resolved"; the adapter's address is in Prediction.Condition.Oracle |
PayoutRedemption | A holder of the winning outcome tokens redeems them for collateral. | PredictionSettlements | Settlement.EventType: "Redemption" |
PositionSplit | Collateral is split into a full set of outcome tokens. | PredictionSettlements | "Split" |
PositionsMerge | A full set of outcome tokens is merged back into collateral. | PredictionSettlements | "Merge" |
Polymarket's adapter contracts (for example the NegRisk adapter) emit their own versions of these events, such as PositionsSplit, PositionsMerged and PositionRedeemed; they map to the same event types. Log.Signature.Name shows which event a row came from.
Resolved outcome of a market
This query returns the resolution of one market by its condition id: when it resolved, the winning outcome, the oracle that reported it and the resolution source. A condition id is unique to one market, while titles such as "Bills vs. Vikings" can repeat across seasons; to search by title instead, replace the Condition filter with Question: { Title: { is: "Bills vs. Vikings" } }. The query uses dataset: combined so it finds markets resolved at any time, not only in recent blocks.
query PolymarketMarketResolution {
EVM(network: matic, dataset: combined) {
PredictionManagements(
where: {
Management: {
EventType: { is: "Resolved" }
Prediction: {
Condition: {
Id: { is: "0xb9a7b47c2b3c56a902bd706745a98c3f627e6f25e3566205b362856f2804c721" }
}
}
}
}
) {
Block {
Time
}
Transaction {
Hash
}
Log {
Signature {
Name
}
SmartContract
}
Management {
EventType
Prediction {
Question {
Title
MarketId
ResolutionSource
}
Condition {
Id
QuestionId
Oracle
}
Outcome {
Index
Label
}
OutcomeToken {
AssetId
}
}
}
}
}
}
Prediction.Outcome.Label is the winning outcome and OutcomeToken.AssetId is the token that pays out. For more resolution queries (live stream of resolutions, latest resolved markets, created vs resolved counts), see PredictionManagements.
Redemptions and payouts for a market
This query returns the redemptions of the same market, largest payout first, plus the total number of redemptions and the total paid out. The filters it uses:
EventType: { is: "Redemption" }keeps payouts only, without splits and merges.IsRepeat: falsecounts each NegRisk payout once (see Key fields).ConditionIdselects the market. To filter by title instead, replace it withQuestion: { Title: { is: "..." } }insidePrediction.
query PolymarketMarketRedemptions {
EVM(network: matic, dataset: combined) {
PredictionSettlements(
limit: { count: 20 }
orderBy: { descending: Settlement_Amounts_CollateralAmountInUSD }
where: {
Settlement: {
EventType: { is: "Redemption" }
IsRepeat: false
Prediction: {
ConditionId: { is: "0xb9a7b47c2b3c56a902bd706745a98c3f627e6f25e3566205b362856f2804c721" }
}
}
}
) {
Block {
Time
}
Transaction {
Hash
}
Settlement {
Holder
Amounts {
Amount
CollateralAmount
CollateralAmountInUSD
}
Prediction {
Question {
Title
}
Outcome {
Label
}
CollateralToken {
Symbol
}
}
}
}
total: PredictionSettlements(
where: {
Settlement: {
EventType: { is: "Redemption" }
IsRepeat: false
Prediction: {
ConditionId: { is: "0xb9a7b47c2b3c56a902bd706745a98c3f627e6f25e3566205b362856f2804c721" }
}
}
}
) {
redemptions: count
total_paid_usd: sum(of: Settlement_Amounts_CollateralAmountInUSD)
}
}
}
Amounts.CollateralAmount is the payout in collateral and CollateralAmountInUSD its USD value. Holder is the address that redeemed: the wallet itself, or the contract that redeemed for it.
Event types
| EventType | Description |
|---|---|
| Split | Collateral converted into outcome tokens (minting). |
| Merge | Outcome tokens converted back to collateral. |
| Redemption | After resolution: winning outcome tokens redeemed for collateral (payout). |
Key fields
- Settlement.EventType —
"Split","Merge", or"Redemption". - Settlement.OutcomeTokenIds — Token IDs from the condition. Split/Merge: all outcome token IDs; Redemption: typically all (redeemer holds winning outcome).
- Settlement.Amounts — Amount (outcome token amount), CollateralAmount, AmountInUSD, CollateralAmountInUSD.
- Settlement.Holder — Address that held the outcome tokens or collateral in the call. When a contract redeems, splits or merges for a trader (a redeem contract, a collateral adapter or the NegRisk adapter), this is the contract's address, not the trader's.
- Settlement.Beneficiary — Wallet the payout or positions belong to. It is the same kind of address as
BuyerandSellerin PredictionTrades, so you can match a wallet's payouts to its trades. When a wallet settles for itself,BeneficiaryequalsHolder. It is empty on Split and Merge rows that the Polymarket exchange contracts make while matching orders; the traders of those fills are theBuyerandSellerin PredictionTrades. - Settlement.IsRepeat —
truewhen the row repeats a payout that another row already records. A NegRisk payout emits two events in one transaction: one from the NegRisk adapter and one from the Conditional Tokens contract, with the same amounts. The Conditional Tokens copy hasIsRepeat: true. FilterIsRepeat: falsewhen you sum or count payouts, so each payout is counted once. - Settlement.Prediction.CollateralToken — Collateral token (e.g. USDC): Name, Symbol, AssetId, SmartContract.
- Settlement.Prediction.Question — Title, MarketId, Id, Image, ResolutionSource, CreatedAt. Use Title to filter by market (e.g. specific question).
- Settlement.Prediction.Outcome — Id, Index, Label (winning outcome on Redemption).
- Settlement.Prediction.Marketplace — ProtocolName, ProtocolFamily, SmartContract.
- Settlement.Prediction.OutcomeToken — Outcome token contract: Name, Symbol, AssetId, SmartContract.
Real-time settlement stream
Subscribe to live Split, Merge, and Redemption events as they occur on Polygon.
subscription PredictionSettlementsStream {
EVM(network: matic) {
PredictionSettlements {
Block {
Time
}
Log {
Signature {
Name
}
SmartContract
}
Settlement {
Amounts {
Amount
AmountInUSD
CollateralAmount
CollateralAmountInUSD
}
EventType
Holder
OutcomeTokenIds
Prediction {
CollateralToken {
Name
Symbol
AssetId
SmartContract
}
ConditionId
OutcomeToken {
Name
Symbol
AssetId
SmartContract
}
Marketplace {
SmartContract
ProtocolFamily
ProtocolName
}
Question {
Title
MarketId
ResolutionSource
Image
CreatedAt
Id
}
Outcome {
Id
Index
Label
}
}
}
Transaction {
Hash
}
}
}
}
Latest settlements (historical)
Fetch the most recent settlements with full details, ordered by block time.
query LatestPredictionSettlements {
EVM(network: matic) {
PredictionSettlements(
limit: { count: 10 }
orderBy: { descending: Block_Time }
) {
Block {
Time
}
Log {
Signature {
Name
}
SmartContract
}
Settlement {
Amounts {
Amount
AmountInUSD
CollateralAmount
CollateralAmountInUSD
}
EventType
Holder
OutcomeTokenIds
Prediction {
CollateralToken {
Name
Symbol
AssetId
SmartContract
}
ConditionId
OutcomeToken {
Name
Symbol
AssetId
SmartContract
}
Marketplace {
SmartContract
ProtocolFamily
ProtocolName
}
Question {
Title
MarketId
ResolutionSource
Image
CreatedAt
Id
}
Outcome {
Id
Index
Label
}
}
}
Transaction {
From
Hash
}
}
}
}
Redemption / Merge / Split count (last 1 hour)
Count how many settlement events occurred in the last hour, grouped by event signature (Split, Merge, Redemption).
query RedemptionsMergeSplitCount {
EVM(network: matic) {
PredictionSettlements(
where: { Block: { Time: { since_relative: { hours_ago: 1 } } } }
) {
count
Log {
Signature {
Name
}
}
}
}
}
Latest whale settlements (large redemptions)
Find the most recent high-value redemptions (e.g. amount ≥ 10,000 USD). Useful for tracking large payouts and whale activity.
query MyQuery {
EVM(network: matic) {
PredictionSettlements(
limit: { count: 10 }
orderBy: { descending: Block_Time }
where: {
Settlement: {
EventType: { is: "Redemption" }
Amounts: { CollateralAmountInUSD: { ge: "10000" } }
}
}
) {
Block {
Time
}
Log {
Signature {
Name
}
SmartContract
}
Settlement {
Amounts {
Amount
AmountInUSD
CollateralAmount
CollateralAmountInUSD
}
EventType
Holder
OutcomeTokenIds
Prediction {
CollateralToken {
Name
Symbol
AssetId
SmartContract
}
ConditionId
OutcomeToken {
Name
Symbol
AssetId
SmartContract
}
Marketplace {
SmartContract
ProtocolFamily
ProtocolName
}
Question {
Title
MarketId
ResolutionSource
Image
CreatedAt
Id
}
Outcome {
Id
Index
Label
}
}
}
Transaction {
From
Hash
}
}
}
}
Top 10 winners of a specific market question
Rank holders by total redeemed amount USD for one market (filter by question title). Replace the title with your market question.
query MyQuery {
EVM(network: matic) {
PredictionSettlements(
limit: {count: 10}
orderBy: {descendingByField: "redeemed_amount"}
where: {Block: {Time: {since_relative: {hours_ago: 1}}},
Settlement: {EventType: {is: "Redemption"},
Prediction: {Question: {Title: {is: "Will Trump nominate Judy Shelton as the next Fed chair?"}}}}}
) {
Settlement {
Holder
}
redeemed_amount: sum(of: Settlement_Amounts_CollateralAmountInUSD selectWhere:{gt:"0"})
count
}
}
}
Top 10 market questions by redeemed amount (last 1 hour)
Aggregated redemptions by market question and sort by total redeemed amount. Use this to see which markets had the most payout activity recently.
query MyQuery {
EVM(network: matic) {
PredictionSettlements(
limit: { count: 10 }
orderBy: { descendingByField: "redeemed_amount" }
where: {
Block: { Time: { since_relative: { hours_ago: 1 } } }
Settlement: { EventType: { is: "Redemption" } }
}
) {
Settlement {
Prediction {
Question {
Title
}
Outcome {
Label
}
}
}
count(distinct:Settlement_Holder)
redeemed_amount: sum(of: Settlement_Amounts_CollateralAmountInUSD)
}
}
}
Top 10 redeemers (last 1 hour)
Rank wallets by total USD redeemed in the last hour across all markets. Useful for leaderboards and whale tracking. The query groups by Beneficiary, so payouts made through a redeem contract or collateral adapter count for the wallet that got the money, and IsRepeat: false counts each NegRisk payout once.
query TopRedeemers {
EVM(network: matic) {
PredictionSettlements(
limit: { count: 10 }
orderBy: { descendingByField: "redeemed_amount" }
where: {
Block: { Time: { since_relative: { hours_ago: 1 } } }
Settlement: { EventType: { is: "Redemption" }, IsRepeat: false }
}
) {
Settlement {
Beneficiary
}
redeemed_amount: sum(of: Settlement_Amounts_CollateralAmountInUSD)
payouts: count
}
}
}
Payouts received by a wallet
List the redemptions paid to one wallet in the last 7 days, with the market and the winning outcome. Beneficiary is the wallet that got the payout; Holder shows the contract that redeemed for it, or the wallet itself when it redeemed directly. IsRepeat: false drops the repeated copy of NegRisk payouts. Replace the address with the wallet you want; add these payouts to the wallet's sells when you build PnL from PredictionTrades.
query PayoutsToWallet {
EVM(network: matic, dataset: realtime) {
PredictionSettlements(
limit: { count: 20 }
orderBy: { descending: Block_Time }
where: {
Block: { Time: { since_relative: { days_ago: 7 } } }
Settlement: {
EventType: { is: "Redemption" }
Beneficiary: { is: "0x466658e9a04e4586fb0ea46abf0a2fd8902f3a55" }
IsRepeat: false
}
}
) {
Block {
Time
}
Transaction {
Hash
}
Settlement {
Beneficiary
Holder
Amounts {
Amount
CollateralAmount
CollateralAmountInUSD
}
Prediction {
Question {
Title
}
Outcome {
Label
}
}
}
}
}
}
Use cases
| Use case | Approach |
|---|---|
| Live settlement feed | Use the real-time subscription above. |
| Recent activity | Use Latest settlements with limit and orderBy: { descending: Block_Time }. |
| Volume by event type | Use Redemption/Merge/Split count with a time window. |
| Large payouts | Use Latest whale settlements with Amounts.Amount: { ge: "..." } and EventType: Redemption. |
| Winners for one market | Use Top 10 winners of a market question with Question.Title: { is: "..." }. |
| Hottest markets by redemptions | Use Top 10 market questions by redeemed amount. |
| Top redeemers | Use Top 10 redeemers (optionally change hours_ago or add more filters). |
| Payouts of one wallet | Use Payouts received by a wallet with Beneficiary: { is: "..." } and IsRepeat: false. |
For market creation and resolution events, see PredictionManagements. For trades, see PredictionTrades.
Ready to run this in production?
Get an API key and run these queries in minutes, or talk to us about plans and enterprise delivery.