Polymarket Rewards Claimer 🎁

Automatically claim your rewards from resolved Polymarket prediction markets using gasless transactions via Relayer API.

🌟 If you find this project useful, please consider giving it a star on GitHub!

---

📖 Overview

This is a reference implementation showing how to programmatically claim rewards from Polymarket prediction markets. The script uses the official Polymarket Relayer API to execute transactions without requiring gas fees.

Use this code as a starting point for your own projects! Feel free to integrate it into your trading bots, monitoring systems, or automation workflows.

---

✨ Features

• ✅ Automatic reward claiming from resolved prediction markets
• ✅ Gasless transactions via Polymarket Relayer API (no MATIC required)
• ✅ GnosisSafe Proxy Wallet support
• ✅ Batch processing of multiple redeemable positions
• ✅ Real-time status updates with transaction confirmation
• ✅ Error handling and retry logic
• ✅ Secure credential management via environment variables

---

🚀 Quick Start

Prerequisites

• Python 3.8 or higher
• Polymarket account with Builder API credentials
• Private key for your EOA (External Owned Account)
• Proxy wallet address (where your positions are held)

Installation

1. Clone the repository

   git clone https://github.com/MixasV/Polymarket-Claimer.git
   cd Polymarket-Claimer/claimer

2. Install dependencies

   pip install -r requirements.txt

3. Configure environment variables

   Copy the example environment file:

   cp .env.example .env

   Edit .env and add your credentials:

   POLYMARKET_PRIVATE_KEY=your_private_key_here
   POLYMARKET_PROXY_WALLET=your_proxy_wallet_address
   BUILDER_API_KEY=your_builder_api_key
   BUILDER_SECRET=your_builder_secret
   BUILDER_PASSPHRASE=your_builder_passphrase

4. Run the claimer

   python claim_rewards.py

---

📁 Project Structure

claimer/
├── claim_rewards.py      # Main script for claiming rewards
├── requirements.txt      # Python dependencies
├── .env.example         # Example environment configuration
├── .env                 # Your actual configuration (gitignored)
└── README.md           # This file

File Descriptions

claim_rewards.py

Main claiming script - This is the core script that handles the entire claiming process.

What it does:

1. Loads credentials from .env file
2. Initializes Polymarket Relayer client with SAFE wallet type
3. Checks if GnosisSafe wallet is deployed (deploys if needed)
4. Fetches all redeemable positions from Polymarket Data API
5. Creates redeemPositions transactions for each position
6. Submits transactions via Relayer API (gasless)
7. Waits for confirmation and displays results

How to run:

python claim_rewards.py

Expected output:

======================================================================
POLYMARKET REWARDS CLAIMER
======================================================================

Author: MixasV
Contact: https://t.me/onEXv
Repository: https://github.com/MixasV/Polymarket-Claimer

📍 Proxy Wallet: 0x65f0f0D46109974E47294236ccb2167ed627C57a

🔧 Initializing Relayer client...
✅ Relayer client initialized (SAFE type)

🔍 Expected Safe: 0x65f0f0D46109974E47294236ccb2167ed627C57a
   Deployed: True

🔍 Fetching redeemable positions...
✅ Found 1 redeemable position(s):

   1. Bitcoin Up or Down - January 12, 9PM ET
      Outcome: Down
      Value: $15

📦 Processing: Bitcoin Up or Down - January 12, 9PM ET
📤 Submitting to Relayer API...
✅ Transaction submitted: 019bb73b-acff-7e8c-bcf9-5e6aa2277ae4
⏳ Waiting for confirmation...

🎉 SUCCESS!
✅ Transaction Hash: 0x8d58c8177f3fcd68eb0b01606987a848c1f445e301aa16aaf75cac346a4166d4
🔍 Polygonscan: https://polygonscan.com/tx/0x8d58c8177f3fcd68eb0b01606987a848c1f445e301aa16aaf75cac346a4166d4

======================================================================
✅ Successfully claimed 1/1 positions
======================================================================

requirements.txt

Lists all Python dependencies required by the claimer.

Installation:

pip install -r requirements.txt

.env.example

Template for environment variables. Copy this file to .env and fill in your credentials.

Required variables:

• POLYMARKET_PRIVATE_KEY - Your EOA private key (with 0x prefix)
• POLYMARKET_PROXY_WALLET - Your Proxy Wallet address
• BUILDER_API_KEY - Polymarket Builder API key
• BUILDER_SECRET - Polymarket Builder secret
• BUILDER_PASSPHRASE - Polymarket Builder passphrase

⚠️ Security Note: Never commit your .env file to version control! It contains sensitive credentials.

---

🔧 Setup Guide

Step 1: Get Builder API Credentials

1. Apply for Polymarket Builder Program at: https://polymarket.com/settings?tab=builder
2. Once approved, you'll receive:
   • BUILDER_API_KEY
   • BUILDER_SECRET
   • BUILDER_PASSPHRASE

Step 2: Find Your Proxy Wallet Address

1. Go to https://polymarket.com
2. Connect your wallet
3. Navigate to Settings → Wallet
4. Copy your Proxy Wallet address (NOT your EOA address)

Example:

• ❌ EOA: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
• ✅ Proxy Wallet: 0x65f0f0D46109974E47294236ccb2167ed627C57a

Step 3: Export Your Private Key

⚠️ IMPORTANT: Your private key controls your funds. Never share it with anyone!

From MetaMask:

1. Click on your account
2. Account Details → Export Private Key
3. Enter password and copy the key

Add 0x prefix if not present:

Original: abc123def456...
Correct:  0xabc123def456...

Step 4: Configure .env File

# Your EOA private key (with 0x prefix)
POLYMARKET_PRIVATE_KEY=0xYOUR_PRIVATE_KEY_HERE

# Your Proxy Wallet address (get from Polymarket settings)
POLYMARKET_PROXY_WALLET=0xYOUR_PROXY_WALLET_ADDRESS

# Builder API credentials (get from Polymarket Builder Program)
BUILDER_API_KEY=your_builder_api_key
BUILDER_SECRET=your_builder_secret
BUILDER_PASSPHRASE=your_builder_passphrase

---

💡 How It Works

Architecture

┌─────────────────────────────────────────────────┐
│  Python Script (claim_rewards.py)               │
├─────────────────────────────────────────────────┤
│  1. Load credentials from .env                  │
│  2. Initialize RelayClient (SAFE type)          │
│  3. Check Safe deployment status                │
│  4. Fetch redeemable positions (Data API)       │
│  5. Create SafeTransaction objects              │
│  6. Sign & submit via Relayer API               │
│  7. Poll for transaction confirmation           │
└─────────────────────────────┬───────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────┐
│  Polymarket Relayer API                         │
├─────────────────────────────────────────────────┤
│  • Validates Builder API credentials            │
│  • Executes transaction on GnosisSafe           │
│  • Pays gas fees (gasless for user)            │
│  • Returns transaction ID                       │
└─────────────────────────────┬───────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────┐
│  Polygon Blockchain                             │
├─────────────────────────────────────────────────┤
│  • CTF Contract (Conditional Token Framework)   │
│  • redeemPositions() function called            │
│  • Winning tokens converted to USDC             │
│  • USDC credited to Proxy Wallet                │
└─────────────────────────────────────────────────┘

Transaction Flow

1. Position Discovery

   • Query Data API for positions with redeemable=true
   • Filter by your Proxy Wallet address

2. Transaction Creation

   • Encode redeemPositions(collateralToken, parentCollectionId, conditionId, indexSets) call
   • Create SafeTransaction object with encoded data
   • Use OperationType.Call for standard contract interaction

3. Signing & Submission

   • Sign transaction with EOA private key
   • Submit to Relayer API with Builder credentials
   • Relayer validates and forwards to blockchain

4. Execution

   • GnosisSafe executes transaction on CTF contract
   • Winning outcome tokens are redeemed for USDC
   • USDC is credited to your Proxy Wallet

5. Confirmation

   • Poll Relayer API for transaction status
   • Wait for STATE_MINED or STATE_CONFIRMED
   • Display Polygonscan link for verification

---

🔐 Security Best Practices

1. Environment Variables

✅ DO:

• Store credentials in .env file
• Add .env to .gitignore
• Use different credentials for testing and production

❌ DON'T:

• Hardcode credentials in source code
• Commit .env to version control
• Share your private key with anyone

2. Private Key Safety

✅ DO:

• Keep your private key encrypted at rest
• Use hardware wallets for large amounts
• Rotate keys periodically

❌ DON'T:

• Store private keys in plain text long-term
• Use the same key across multiple applications
• Share private keys via email or chat

3. API Credentials

✅ DO:

• Request minimum necessary permissions
• Monitor API usage for anomalies
• Revoke unused credentials

❌ DON'T:

• Expose Builder API keys in client-side code
• Use production credentials for testing
• Share API keys publicly

---

🛠️ Customization

Integrate into Your Project

Example: Add to existing trading bot

from claim_rewards import get_redeemable_positions, create_redeem_transaction

# In your trading bot's main loop
def check_and_claim_rewards(proxy_wallet: str, relayer_client):
    """Check for claimable rewards and auto-claim"""
    positions = get_redeemable_positions(proxy_wallet)
    
    for pos in positions:
        redeem_tx = create_redeem_transaction(pos['conditionId'])
        response = relayer_client.execute([redeem_tx], f"Auto-claim: {pos['title']}")
        result = response.wait()
        
        if result:
            print(f"✅ Claimed {pos['currentValue']} from {pos['title']}")

Scheduled Execution

Run claimer every hour via cron:

# Edit crontab
crontab -e

# Add this line (runs every hour)
0 * * * * cd /path/to/Polymarket-Claimer/claimer && /usr/bin/python3 claim_rewards.py >> /var/log/polymarket-claimer.log 2>&1

Batch Processing with Custom Filters

# Claim only high-value positions (>$100)
positions = get_redeemable_positions(proxy_wallet)
high_value = [p for p in positions if float(p['currentValue']) >= 100]

for pos in high_value:
    # Process only valuable positions
    ...

---

🐛 Troubleshooting

Common Issues

1. "Missing required environment variables"

Cause: .env file not configured correctly

Solution:

# Copy example file
cp .env.example .env

# Edit with your credentials
nano .env

2. "Safe not deployed"

Cause: First time using Relayer with this wallet

Solution: Script will automatically deploy Safe. Wait for deployment confirmation.

3. "No redeemable positions found"

Cause: All positions already claimed or no resolved markets

Solution: This is normal. Script will exit gracefully.

4. "Invalid Builder API credentials"

Cause: Wrong API key, secret, or passphrase

Solution:

• Verify credentials at https://polymarket.com/settings?tab=builder
• Check for extra spaces or newlines in .env
• Ensure you're approved for Builder Program

5. "Transaction failed to confirm"

Cause: Network congestion or Relayer issues

Solution:

• Wait and retry after a few minutes
• Check Relayer API status
• Verify your transaction on Polygonscan

Debug Mode

Enable verbose logging:

import logging
logging.basicConfig(level=logging.DEBUG)

---

📚 Technical Details

Smart Contracts

Contract	Address	Purpose
CTF (Conditional Token Framework)	0x4d97dcd97ec945f40cf65f87097ace5ea0476045	Handles position redemption
USDCe (USD Coin)	0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174	Collateral token

API Endpoints

Endpoint	Purpose
https://relayer-v2.polymarket.com	Relayer API for gasless transactions
https://data-api.polymarket.com/positions	Position data and redeemability status

Libraries Used

• py-builder-relayer-client - Official Polymarket Relayer client
• py-builder-signing-sdk - Builder authentication and signing
• web3.py - Ethereum/Polygon interaction
• requests - HTTP client for Data API

---

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Report bugs - Open an issue with detailed reproduction steps
2. Suggest features - Share your ideas for improvements
3. Submit PRs - Fork, code, and create a pull request
4. Improve docs - Help make the documentation clearer

Coding Standards:

• Follow PEP 8 style guide
• Add docstrings to functions
• Include error handling
• Test before submitting

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License Summary:

• ✅ Commercial use allowed
• ✅ Modification allowed
• ✅ Distribution allowed
• ✅ Private use allowed
• ⚠️ No warranty provided
• ⚠️ No liability accepted

---

👤 Author

MixasV

• Telegram: @onEXv
• GitHub: @MixasV

For questions, suggestions, or collaboration opportunities, feel free to reach out!

---

⭐ Support

If this project helped you automate your Polymarket rewards, please:

1. ⭐ Star this repository on GitHub
2. 📢 Share it with other Polymarket traders
3. 💬 Provide feedback via issues or Telegram

Your support helps maintain and improve this project!

---

🔍 Keywords

polymarket prediction-markets crypto automation claiming rewards claimer relayer gasless-transactions polygon conditional-tokens ctf gnosis-safe safe-wallet trading-bot defi blockchain ethereum web3 python builder-api

---

⚠️ Disclaimer

This software is provided as a reference implementation for educational purposes.

Use at your own risk:

• Always test with small amounts first
• Review all transactions before execution
• Keep your private keys secure
• No warranty or guarantees provided
• Author is not responsible for any losses

This is not financial advice. Always do your own research before trading or investing in prediction markets.

---

📚 Additional Resources

• Polymarket Documentation
• Polymarket Builder Program
• Relayer Client Docs
• CTF Contract

---

Made with ❤️ by MixasV

⭐ Star this repo • 🐛 Report Bug • 💡 Request Feature