Poly Redeem Bot

An automated bot that monitors and redeems redeemable positions on Polymarket using the Builder Relayer service.

Overview

This bot continuously monitors your Polymarket positions and automatically redeems them when they become redeemable. It:

• Polls the Polymarket Data API for redeemable positions
• Batches multiple redeems into a single transaction for efficiency
• Handles relayer quota limits with automatic retry logic
• Supports both PROXY and SAFE wallet transaction types
• Monitors transaction status until confirmed on-chain

Prerequisites

• Node.js (v18 or higher recommended)
• A Polymarket account with positions
• Polymarket Builder API credentials (key, secret, passphrase)
• An Ethereum private key that controls your Polymarket wallet
• An RPC endpoint for Polygon network

Installation

1. Clone the repository:

git clone <repository-url>
cd poly-redeem

2. Install dependencies:

npm install

3. Copy the example environment file:

cp .env.example .env

4. Configure your environment variables (see Configuration below)

Configuration

Create a .env file in the root directory with the following variables:

Required Variables

• PRIVATE_KEY - Your Ethereum private key (without 0x prefix) that controls the wallet with Polymarket positions
• POLY_BUILDER_API_KEY - Your Polymarket Builder API key
• POLY_BUILDER_SECRET - Your Polymarket Builder API secret
• POLY_BUILDER_PASSPHRASE - Your Polymarket Builder API passphrase
• POLY_USER_ADDRESS - The Ethereum address where your Polymarket positions are held
• RPC_URL - Polygon RPC endpoint URL (e.g., from Alchemy, Infura, or QuickNode)

Optional Variables

• POLL_INTERVAL_MS - How often to check for redeemable positions (default: 60000 = 1 minute)
• TX_STATUS_POLL_MS - How often to poll transaction status (default: 5000 = 5 seconds)
• TX_STATUS_MAX_POLLS - Maximum number of status polls before timeout (default: 36)
• POSITIONS_SIZE_THRESHOLD - Minimum position size to consider (default: 1)
• POSITIONS_LIMIT - Maximum positions to fetch per API call (default: 100, max: 500)
• POSITIONS_SORT_BY - Sort field for positions (default: TOKENS)
• POSITIONS_SORT_DIRECTION - Sort direction: ASC or DESC (default: DESC)
• POLY_DATA_API_URL - Polymarket Data API base URL (default: https://data-api.polymarket.com)
• RELAYER_URL - Polymarket Relayer service URL (default: https://relayer-v2.polymarket.com/)
• RELAYER_TX_TYPE - Transaction type: PROXY or SAFE (default: SAFE)
• PROXY_GAS_LIMIT_PER_REDEEM - Gas limit per redeem in a batch (default: 153500)
• PROXY_GAS_LIMIT_CAP - Maximum gas limit for proxy transactions (default: 2000000)
• CTF_ADDRESS - Conditional Token Framework contract address (default: 0x4d97dcd97ec945f40cf65f87097ace5ea0476045)
• COLLATERAL_TOKEN - Collateral token address (default: 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174 for USDCe)

Transaction Type Configuration

The bot supports two transaction types:

• SAFE (default): Uses a Safe wallet for transaction execution. The bot will automatically deploy the Safe if needed.
• PROXY: Uses a proxy wallet. The PRIVATE_KEY must control the proxy wallet address, and POLY_USER_ADDRESS must match the derived proxy wallet address.

The bot validates that your PRIVATE_KEY and POLY_USER_ADDRESS are correctly configured for the selected transaction type.

Usage

Continuous Mode (Default)

Run the bot continuously, polling for redeemable positions:

npm start

or

node src/bot.js

The bot will:

1. Check for redeemable positions every POLL_INTERVAL_MS milliseconds
2. Batch multiple redeems into a single transaction
3. Submit transactions via the Polymarket Builder Relayer
4. Monitor transaction status until confirmed
5. Handle relayer quota limits with automatic retries

One-Time Mode

Run the bot once to check and redeem positions immediately:

npm run redeem:once

or

node src/bot.js --once

How It Works

1. Position Discovery: The bot queries the Polymarket Data API for redeemable positions associated with your POLY_USER_ADDRESS.

2. Position Filtering: Only positions that are:

   • Redeemable (market resolved)
   • Meet the POSITIONS_SIZE_THRESHOLD
   • Are binary markets (can infer index sets)

3. Batching: Positions are grouped by conditionId and batched together. The bot prevents duplicate redeems by tracking recently redeemed conditions (10-minute cooldown).

4. Transaction Building: For each condition, the bot builds a redeemPositions transaction to the Conditional Token Framework contract.

5. Submission: Transactions are submitted via the Polymarket Builder Relayer service, which handles gas fees and execution.

6. Monitoring: The bot monitors transaction status until it reaches a terminal state (STATE_CONFIRMED, STATE_MINED, STATE_FAILED, or STATE_INVALID).

7. Quota Handling: If the relayer quota is exceeded, the bot automatically waits for the specified retry period before attempting again.

Features

• Automatic Batching: Multiple redeems are combined into a single transaction to save gas
• Duplicate Prevention: Tracks recently redeemed conditions to avoid duplicate submissions
• Quota Management: Automatically handles relayer rate limits with exponential backoff
• Transaction Monitoring: Tracks transaction status until on-chain confirmation
• Error Handling: Graceful error handling with detailed logging
• Flexible Configuration: Extensive configuration options via environment variables

Logging

The bot provides detailed console logging with timestamps:

• Position discovery and filtering
• Batch creation and submission
• Transaction status updates
• Error messages and warnings
• Quota limit notifications

Security Notes

• Never commit your .env file - It contains sensitive credentials
• Keep your private key secure - Anyone with access can control your wallet
• Use environment-specific keys - Consider using different API keys for testing vs production
• Review transactions - Monitor the bot's activity, especially when first deploying

Troubleshooting

"RELAYER_TX_TYPE mismatch" Error

This error occurs when your PRIVATE_KEY and POLY_USER_ADDRESS don't match the expected wallet type:

• For RELAYER_TX_TYPE=PROXY: The PRIVATE_KEY must control the proxy wallet, and POLY_USER_ADDRESS must be the derived proxy wallet address
• For RELAYER_TX_TYPE=SAFE: The PRIVATE_KEY must be a signer for the Safe, and POLY_USER_ADDRESS must be the Safe address

Relayer Quota Exceeded

If you see quota exceeded errors, the bot will automatically wait and retry. You can:

• Increase POLL_INTERVAL_MS to reduce submission frequency
• Wait for the quota to reset (usually 1 hour)
• Contact Polymarket support if you need higher limits

"Unable to infer indexSets" Warning

This occurs for non-binary markets where the bot cannot automatically determine the index sets. The bot will skip these positions. Binary markets (Yes/No) are fully supported.

License

ISC