Settlements API

Settlements record the payout amounts for positions after a market is resolved. The prediction engine creates settlement records — operators query these records to determine how much to credit each player's wallet.

Authentication: X-Api-Key header required.

Settlement Flow

Market RESOLVED → Trigger Settlement → Settlement Records Created → Operator Queries Payouts → Operator Credits Players

Step 1: Trigger Settlement

After resolving a market, trigger the settlement process:

POST /api/v1/markets/{id}/settle

This will:

1. Cancel all remaining open orders in the market
2. Calculate payouts for each position
3. Create settlement records

Response:

{
  "success": true,
  "data": {
    "marketId": "market-uuid",
    "totalPositions": 25,
    "successCount": 25,
    "failedCount": 0,
    "totalPayout": "1250.00",
    "cancelledOrders": 3,
    "settlements": [
      {
        "id": "settlement-uuid",
        "positionId": "position-uuid",
        "marketId": "market-uuid",
        "outcomeId": "outcome-uuid",
        "operatorId": "operator-uuid",
        "playerId": "player-123",
        "shares": "100",
        "payoutPerShare": "1",
        "totalPayout": "100",
        "transactionId": null,
        "status": "COMPLETED",
        "errorMessage": null,
        "settledAt": "2026-02-18T23:00:00.000Z",
        "createdAt": "2026-02-18T23:00:00.000Z",
        "updatedAt": "2026-02-18T23:00:00.000Z"
      }
    ],
    "errors": []
  }
}

Step 2: Query Settlement Status

Check the progress of settlement processing:

GET /api/v1/markets/{id}/settlement-status

Response:

{
  "success": true,
  "data": {
    "marketId": "market-uuid",
    "totalPositions": 25,
    "pendingCount": 0,
    "processingCount": 0,
    "completedCount": 25,
    "failedCount": 0,
    "totalPayout": "1250.00",
    "completedPayout": "1250.00"
  }
}

Step 3: Query Settlement Payouts

Retrieve settlement records to determine player payouts:

GET /api/v1/settlements

Query Parameters:

Parameter	Type	Description
marketId	string	Filter by market
playerId	string	Filter by player

Example:

curl "https://polymarket.sandbox.playbatman.com/api/v1/settlements?marketId=market-uuid" \
  -H "X-Api-Key: your-api-key"

Response:

{
  "success": true,
  "data": [
    {
      "id": "settlement-uuid",
      "positionId": "position-uuid",
      "marketId": "market-uuid",
      "outcomeId": "winning-outcome-uuid",
      "operatorId": "operator-uuid",
      "playerId": "player-123",
      "shares": "100",
      "payoutPerShare": "1",
      "totalPayout": "100",
      "transactionId": null,
      "status": "COMPLETED",
      "errorMessage": null,
      "settledAt": "2026-02-18T23:00:00.000Z",
      "createdAt": "2026-02-18T23:00:00.000Z",
      "updatedAt": "2026-02-18T23:00:00.000Z"
    },
    {
      "id": "settlement-uuid-2",
      "positionId": "position-uuid-2",
      "marketId": "market-uuid",
      "outcomeId": "losing-outcome-uuid",
      "operatorId": "operator-uuid",
      "playerId": "player-456",
      "shares": "50",
      "payoutPerShare": "0",
      "totalPayout": "0",
      "transactionId": null,
      "status": "COMPLETED",
      "errorMessage": null,
      "settledAt": "2026-02-18T23:00:00.000Z",
      "createdAt": "2026-02-18T23:00:00.000Z",
      "updatedAt": "2026-02-18T23:00:00.000Z"
    }
  ]
}

Step 4: Retry Failed Settlements

If any settlements failed, you can retry them:

POST /api/v1/markets/{id}/retry-settlements

Response: Same shape as the settle response.

Payout Calculation

• Winning outcome: payoutPerShare = 1.00 — each share pays out 1 unit of the market currency
• Losing outcome: payoutPerShare = 0.00 — no payout

Example:

• Player bought 100 shares of "Yes" at $0.65 → cost: $65.00
• Market resolves "Yes" → payout: 100 shares * $1.00 = $100.00
• Profit: $100.00 - $65.00 = $35.00

Settlement Fields

Field	Type	Description
id	string	Settlement UUID
positionId	string	Position being settled
marketId	string	Market UUID
outcomeId	string	Outcome UUID
operatorId	string	Operator UUID
playerId	string	Player identifier
shares	string (decimal)	Number of shares in the position
payoutPerShare	string (decimal)	Payout per share (1 for winning, 0 for losing)
totalPayout	string (decimal)	Total payout amount (shares * payoutPerShare)
transactionId	string | null	Operator-assigned transaction reference
status	string	PENDING, PROCESSING, COMPLETED, or FAILED
errorMessage	string | null	Error details if settlement failed
settledAt	string (ISO 8601) | null	When settlement was completed
createdAt	string (ISO 8601)	Record creation time
updatedAt	string (ISO 8601)	Last update time

Operator Responsibilities

important

The prediction engine records settlement amounts but does not transfer funds. As an operator, you must:

1. Query settlement records after market settlement
2. Use the playerId field on each settlement to identify the player
3. Credit your players' wallets with the totalPayout amounts
4. Track which settlements you have processed on your side

Error Codes

Code	Description
SETTLEMENT_FAILED	Settlement processing encountered an error
SETTLEMENT_ALREADY_COMPLETED	Settlement has already been completed