Skip to main content
POST
/
api
/
v1
/
settlements
/
settle
/
{market_id}
Settle Position
curl --request POST \
  --url https://api.example.com/api/v1/settlements/settle/{market_id}
{
  "settled": true,
  "payout": 123,
  "original_size": 123,
  "winning_outcome": "<string>",
  "was_winner": true,
  "message": "<string>"
}

​
Usage

result = client.settle_position(
    market_id="0x1234...abcd",
    token_id="12345678901234567890"  # Optional
)

​
Parameters

​
market_id
string
required
The market ID (condition ID) to settle.
​
token_id
string
Optional. Specific token ID to settle (for markets where you hold multiple outcomes).

​
Requirements

  • Market must be closed on Polymarket
  • Market must have a winning outcome determined
  • You must have an active position in the market

​
Response

​
settled
boolean
Whether settlement was successful.
​
payout
number
Amount credited to your balance (0 if lost, shares × $1 if won).
​
original_size
number
Number of shares that were settled.
​
winning_outcome
string
Which outcome won the market.
​
was_winner
boolean
Whether you held winning shares.
​
message
string
Status message.

​
Example

from polyhush import PolyhushClient, PolyhushAPIError

client = PolyhushClient(api_key="your-api-key")

try:
    result = client.settle_position(
        market_id="0x1234...abcd",
        token_id="12345678901234567890"
    )
    
    if result['settled']:
        if result['was_winner']:
            print(f"🎉 You won! Payout: ${result['payout']:.2f}")
        else:
            print(f"📉 Position settled (lost)")
        print(f"Shares settled: {result['original_size']}")
        print(f"Winning outcome: {result['winning_outcome']}")
    else:
        print(f"Settlement failed: {result['message']}")
        
except PolyhushAPIError as e:
    print(f"Error: {e.message}")

​
Response (Winner)

{
  "settled": true,
  "payout": 100.00,
  "original_size": 100,
  "winning_outcome": "Yes",
  "was_winner": true,
  "message": "Position settled successfully"
}

​
Response (Loser)

{
  "settled": true,
  "payout": 0,
  "original_size": 50,
  "winning_outcome": "No",
  "was_winner": false,
  "message": "Position settled successfully"
}

​
Payout Calculation

PositionMarket OutcomePayout
Yes sharesYes winsshares × $1.00
Yes sharesNo wins$0.00
No sharesNo winsshares × $1.00
No sharesYes wins$0.00
Winning shares are always worth 1.00eachatsettlement.Ifyouboughtat1.00 each at settlement. If you bought at 0.60, your profit is $0.40 per share.

​
Settlement Workflow

# Recommended workflow
pending = client.get_pending_settlements()

for market in pending:
    if market['can_settle']:
        print(f"Settling: {market['market_question']}")
        print(f"Your bet: {market['your_outcome']}")
        
        result = client.settle_position(
            market['market_id'], 
            market['token_id']
        )
        
        if result['settled']:
            print(f"Payout: ${result['payout']:.2f}")