Core concepts

Market resolution & voids

How a market settles, how to read a split or refunded outcome, and what happens to positions and open orders

When a market ends, PE records how each outcome settled and updates the user's positions. Most markets settle to one winner. Some settle as a split, where every share pays part of a dollar, or as a void, where holders get their stake back. This page shows how to read each case and what the user has to do.

Market status

closed and resolved in this section are market status, not position status.

StatusMeaning
closedMarket status: trading has stopped. On some venues a voided market also ends in closed.
resolvedMarket status: the venue has published how the market settled.

Status alone does not tell you what an outcome pays. Read the outcome fields below.

Reading an outcome

Read refundAtCost first: when it is true the market was voided and a share pays the user's entry price. If payoutPerShare is set, that is the USD paid per share, from 0 to 1. Otherwise winner: true pays $1 divided by the number of winning outcomes, winner: false pays $0, and winner: null is not settled yet.

Each outcome on GET /venue-markets, GET /venue-events and GET /venue-market-outcomes carries those fields. Check them in this order:

CheckMeaningWhat a share pays
refundAtCost: trueThe market was voided and holders are refunded.The user's entry price
payoutPerShare is setThe venue published a per-share payout.payoutPerShare USD (0 to 1)
winner: trueThe outcome won.$1 divided by the number of winning outcomes
winner: falseThe outcome lost.$0
winner: nullNot settled yet.Keep showing the market price

A void often shows up as more than one outcome with winner: true. Always check refundAtCost and payoutPerShare before assuming a winner pays $1.

Examples:

  • Polymarket 50/50. Both outcomes have winner: true and payoutPerShare: 0.5. Each share pays $0.50.
  • Refund at cost. Every outcome has refundAtCost: true. A position bought at 0.42 is refunded at $0.42 a share.

Inferred winners

Outcomes also carry winnerSource, which says who decided winner. It is null when winner is null, and also on winners recorded before this field existed:

winnerSourceMeaning
venueThe venue's own result. Safe to settle on.
matchedInferred by PE because this venue named no winner yet: from matched markets on other venues, or from the same game's moneyline for a soccer ±0.5 spread. Provisional.
nullwinner is null, or the winner predates this field.

Settle held positions only when winnerSource is "venue" or refundAtCost is true. Treat matched as provisional.

Positions after settlement

GET /execution/positions reflects settlement for each outcome the user holds:

  • winner is set, currentPrice becomes the payout per share, and priceSource is settled.
  • redeemStatus tells you whether to call POST /execution/redeem:
redeemStatusMeaning
eligibleClaim the payout with POST /execution/redeem.
pendingA claim is in progress.
redeemedAlready claimed or settled.
ineligibleNothing to claim through PE: the outcome lost, the venue settles on its own, or the position is self-custody and is claimed on the venue.

A position's status: closed is position status: that holding is settled or sold. It is not market status closed.

Redeem

POST /execution/redeem claims outcomes whose redeemStatus is eligible. mode (live or paper) is optional.

SDK
const claimed = await client.redeem({ venueMarketOutcomeIds: [outcomeId] });

Redeem winnings for resolved positions.

The call returns before an EVM claim finishes. Read redeemId and each results[] entry's status (submitted, confirmed, ineligible, or rejected) and reason. That body is not the settlement record above.

Auto-redeem. When a market resolves, PE automatically claims payouts for your users' winning positions on venues that require an on-chain claim (Polymarket), including winnings that were left unclaimed before this feature launched. The claim starts about 2 minutes after PE sees the market resolve (an inherent delay so the venue's on-chain payout is in place first), so expect the payout a few minutes after the market closes, depending on how quickly the venue resolves it. On by default; turn it off in the dashboard under Settings → Auto-redeem winning positions.

By venue

In this table, closed and resolved are market status.

VenueHow a split or void appearsWhat the user does
Polymarketresolved. A 50/50 has both outcomes winner: true with payoutPerShare: 0.5.Managed: call POST /execution/redeem, which pays $0.50 a share. Self-custody: redeem on Polymarket.
Hyperliquidresolved. Split or scalar settlements set payoutPerShare on each outcome.Nothing. Positions settle automatically.

Open orders

When a market closes or resolves, or its end date passes, PE cancels the user's resting managed limit orders on the venue. They end with status expired.

Self-custody limit orders on Polymarket and Hyperliquid are different: PE does not cancel them. They stay on the venue until the venue expires them or the user cancels. See Limit orders.

Webhooks

The webhook markets.resolved and the socket event market_resolved are different channels, and EVM redeem completion is the socket event redeem_event, not market_resolved. On either settlement channel, read refundAtCost and payoutPerShare before you show an amount. When more than one outcome has winner: true, the market settled as a split or void. payoutPerShare is absent when the venue has not reported it. winnerSource is absent when winner is, and on winners recorded before this field. See the webhook event reference.

On this page