Skip to main content
GET
/
api
/
v1
/
settlements
/
status
/
{market_id}
Get Settlement Status
curl --request GET \
  --url https://api.example.com/api/v1/settlements/status/{market_id}
{
  "settled": true,
  "status": "<string>",
  "market_id": "<string>",
  "market_question": "<string>",
  "winning_outcome": "<string>",
  "winning_outcome_index": 123,
  "user_payout": 123,
  "user_position_size": 123,
  "user_won": true,
  "had_position": true,
  "can_withdraw": true,
  "settled_at": "<string>",
  "redemption_tx_hash": "<string>",
  "total_user_payout": 123,
  "users_credited": 123,
  "error_message": "<string>"
}

​
Usage

status = client.get_settlement_status(market_id="0x1234...abcd")
This provides more detailed information than get_market_settlement(), including settlement lifecycle status and on-chain redemption details.

​
Parameters

​
market_id
string
required
The market ID (condition ID) to check.

​
Response

​
settled
boolean
Whether market has been completely settled.
​
status
string
Settlement lifecycle status:
  • NOT_SETTLED - Settlement not started
  • REDEEMING - On-chain redemption in progress
  • DISTRIBUTING - Distributing funds to users
  • COMPLETED - Settlement complete
  • FAILED - Settlement failed
​
market_id
string
Market identifier.
​
market_question
string
The market question.
​
winning_outcome
string
Name of winning outcome.
​
winning_outcome_index
integer
Index of winning outcome.
​
user_payout
number
Amount credited to you.
​
user_position_size
number
Size of your position.
​
user_won
boolean
Whether you held winning shares.
​
had_position
boolean
Whether you had a position in this market.
​
can_withdraw
boolean
Whether you can now withdraw funds.
​
settled_at
string
When settlement completed.
​
redemption_tx_hash
string
Polygon transaction hash for on-chain redemption.
​
total_user_payout
number
Total USDC distributed to all users.
​
users_credited
integer
Number of users who received payouts.
​
error_message
string
Error details if status is FAILED.

​
Example

from polyhush import PolyhushClient

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

status = client.get_settlement_status(market_id="0x1234...abcd")

print(f"Market: {status['market_question']}")
print(f"Status: {status['status']}")

if status['settled']:
    win_text = "WON" if status['user_won'] else "LOST"
    print(f"\n✅ Settlement Complete")
    print(f"   You {win_text}!")
    print(f"   Payout: ${status['user_payout']:.2f}")
    print(f"   Position: {status['user_position_size']} shares")
    print(f"   Settled at: {status['settled_at']}")
    
    if status.get('redemption_tx_hash'):
        print(f"\n🔗 Transaction: {status['redemption_tx_hash']}")
        print(f"   View on Polygonscan: https://polygonscan.com/tx/{status['redemption_tx_hash']}")
        
elif status['status'] == 'REDEEMING':
    print("\n⏳ Settlement in progress...")
    print("   Shares being redeemed on-chain")
    
elif status['status'] == 'FAILED':
    print(f"\n❌ Settlement failed: {status.get('error_message')}")

​
Response (Completed)

{
  "settled": true,
  "status": "COMPLETED",
  "market_id": "0x1234...abcd",
  "market_question": "Will BTC exceed $100k by end of 2024?",
  "winning_outcome": "Yes",
  "winning_outcome_index": 0,
  "user_payout": 100.00,
  "user_position_size": 100,
  "user_won": true,
  "had_position": true,
  "can_withdraw": true,
  "settled_at": "2024-12-31T23:59:00Z",
  "redemption_tx_hash": "0xabc123...",
  "total_user_payout": 50000.00,
  "users_credited": 150
}

​
Response (In Progress)

{
  "settled": false,
  "status": "REDEEMING",
  "market_id": "0x1234...abcd",
  "market_question": "Will BTC exceed $100k by end of 2024?",
  "winning_outcome": "Yes",
  "had_position": true
}

​
Polling for Settlement

import time

def wait_for_settlement(client, market_id, timeout=300):
    """Wait for settlement to complete"""
    start = time.time()
    
    while time.time() - start < timeout:
        status = client.get_settlement_status(market_id)
        
        if status['settled']:
            return status
        elif status['status'] == 'FAILED':
            raise Exception(f"Settlement failed: {status.get('error_message')}")
        
        print(f"Status: {status['status']}... waiting")
        time.sleep(10)
    
    raise TimeoutError("Settlement did not complete in time")

# Usage
status = wait_for_settlement(client, "0x1234...abcd")
print(f"Settled! Payout: ${status['user_payout']:.2f}")