> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agg.market/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To integrate AGG, start with Quickstart: REST (https://docs.agg.market/quickstart/rest), then Order lifecycle & statuses (https://docs.agg.market/concepts/order-lifecycle).
> Track every trade until it reaches a terminal status. Before retrying a failed or timed-out call, read Errors, retries & idempotency (https://docs.agg.market/concepts/errors).
> The API reference is generated from https://docs.agg.market/openapi/openapi.json.

# Claim winnings

> Find settled positions that need a claim, call POST /execution/redeem, and track the result

Some venues pay a settled position on their own. Others need a claim. `POST /execution/redeem`
claims the user's managed positions as USDC. It needs no wallet prompt.

## Automatic or manual, by venue

| Venue | Claim |
| - | - |
| Polymarket, Limitless, Predict, Myriad | Manual. Call `POST /execution/redeem`. |
| Kalshi, Hyperliquid, BetDEX, TipRun, PRED | Automatic. No call. |
| ProphetX direct accounts | Automatic, in the user's own ProphetX account. |
| Opinion, Probable, Novig, ProphetX clearinghouse | No claim through AGG. The call returns `ineligible`. |

Self-custody positions are never claimed through AGG. The user claims them on the venue.

You do not need this table at run time. Read `redeemStatus` on each position instead.

## 1. Find claimable positions

`GET /execution/positions` returns one group per market. Claim the groups whose `redeemStatus` is
`eligible`, using the winning outcome ids in `venueBreakdown`.

<CodeGroup>
  ```ts SDK theme={null}
  const positions = await client.getExecutionPositions();
  const outcomeIds = positions.data
    .filter((p) => p.redeemStatus === "eligible")
    .flatMap((p) => p.venueMarket.venueMarketOutcomes)
    .filter((o) => o.winner === true)
    .flatMap((o) => o.venueBreakdown.map((leg) => leg.venueMarketOutcomeId));
  ```

  ```bash cURL theme={null}
  curl -s https://api.agg.market/execution/positions \
    -H "x-app-id: $AGG_APP_ID" -H "Authorization: Bearer $ACCESS_TOKEN" \
    | jq '[.data[] | select(.redeemStatus == "eligible") | .venueMarket.venueMarketOutcomes[]
           | select(.winner == true) | .venueBreakdown[].venueMarketOutcomeId]'
  ```
</CodeGroup>

[Get user positions](/api-reference/portfolio/get-user-positions)

| `redeemStatus` | Meaning |
| - | - |
| `eligible` | Claim it. |
| `pending` | A claim is in progress. Wait. |
| `redeemed` | Paid. Nothing to do. |
| `ineligible` | Nothing to claim through AGG: not settled yet, lost, settled by the venue, or self-custody. |

A split or void can mark more than one outcome as a winner. Read
[Market resolution & voids](/concepts/market-resolution) before you show an amount.

## 2. Redeem

<CodeGroup>
  ```ts SDK theme={null}
  if (outcomeIds.length > 0) {
    const { redeemId, results } = await client.redeem({ venueMarketOutcomeIds: outcomeIds });
    for (const r of results) console.log(redeemId, r.venueMarketOutcomeId, r.status, r.reason);
  }
  ```

  ```bash cURL theme={null}
  curl -s -X POST https://api.agg.market/execution/redeem \
    -H "x-app-id: $AGG_APP_ID" -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "content-type: application/json" \
    -d '{ "venueMarketOutcomeIds": ["OUTCOME_ID"] }'
  ```
</CodeGroup>

[Redeem winnings for resolved positions](/api-reference/trading/redeem-winnings-for-resolved-positions)

Send `x-app-id` and the user's access token. `mode` (`live` or `paper`) is optional and defaults to
live. Live claims are refused with `403` where trading is not available in the user's region.

## 3. Read the result

The call returns before an on-chain claim finishes. Each `results[]` entry has a `status` and a
`reason`:

| `status` | Meaning | What to do |
| - | - | - |
| `submitted` | The claim is on its way. | Wait for completion (below). |
| `confirmed` | Done, or nothing was owed. | Nothing. |
| `ineligible` | Not claimable now. `reason` says why, for example `market not resolved`, `market winner not yet available`, `already redeemed`, or `venue ... does not support redeem`. | Retry later only for the first two. |
| `rejected` | Refused. `reason` says why, for example `not owned by user or unknown id`, `redeem in progress`, or `position reserved for execution`. | Fix the id, or retry after the other claim or sell finishes. |

To see completion, read positions again until `redeemStatus` is `redeemed`, or listen for
`redeem_event` on the WebSocket.

## Related

* [Market resolution & voids](/concepts/market-resolution)
* [Portfolio](/recipes/portfolio)
* [Execution](/concepts/execution)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.