PolyArb

PolyArb is a specialized tool for discovering and exploiting arbitrage opportunities on Polymarket, the world's largest prediction market. It provides a CLI and a daemon to manage wallets, positions, and execute trades programmatically.

Features

• Arbitrage Discovery: Automatically scans markets for arbitrage loops and profitable combinations.
• Automated Trading: Execute trades across multiple markets simultaneously.
• Wallet Management: Generate, provision, and manage multiple wallets (including Gnosis Safe proxy wallets) for split-trading strategies.
• Position Management: View, claim, and liquidate positions efficiently.
• Analysis Tools: ROI calculators and market probability analyzers.

Prerequisites

• Python 3.11+
• A Polygon (MATIC) wallet with some MATIC for gas and USDC for trading.

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/polyarb.git
   cd polyarb

2. Install dependencies:

   pip install -r requirements.txt

3. Initialize submodules (if applicable):

   git submodule update --init --recursive

Configuration

1. Copy the example environment file:

   cp .env.example .env

2. Edit .env and add your Polygon wallet private key:

   POLYGON_WALLET_PRIVATE_KEY=your_private_key_here

Usage

The application is controlled via the cli.py script.

General Commands

• List all commands:

  python cli.py --help

• Generate Wallets: Create new wallets for trading.

  python cli.py generate-wallets --num-wallets 5

• View Wallets: Check balances and active positions.

  python cli.py view-wallets

• Provision Wallets: Fund your generated wallets with MATIC and USDC, and deploy proxy wallets.

  python cli.py provision-wallets --matic-amount 0.1 --usdc-amount 10

Trading & Arbitrage

• Find Arbitrage: Scan specifically defined bundles in config.yaml for opportunities.

  python cli.py arbitrage --min-roi 0.05

• Run Daemon: Start the automated trading bot.

  python cli.py arbitrage-daemon --min-roi 0.05 --max-amount 10

• Close Markets: Find markets nearing expiration with specific probability ranges.

  python cli.py close-markets --min-prob 40 --max-prob 60

Position Management

• Claim Winnings: Redeem winning positions for USDC.

  python cli.py claim-positions

• Sell Positions: Liquidate current positions at market price.

  python cli.py sell-positions

Case Study: 2024 US Presidential Election

This tool was successfully used during the 2024 US Presidential Election to capitalize on high-volume overlapping markets. The core strategy relied on breaking down the election into 4 mutually exclusive "atomic" outcomes based on the two major variables: the Presidency winner and the Popular Vote winner.

Atomic Outcomes

We assigned a number to each possible scenario:

1. Outcome 1 (RR): Republican wins Presidency AND Popular Vote.
2. Outcome 2 (RD): Republican wins Presidency but Democrats win Popular Vote.
3. Outcome 3 (DR): Democrat wins Presidency but Republicans win Popular Vote.
4. Outcome 4 (DD): Democrat wins Presidency AND Popular Vote.

Derived Markets (The "OR" Logic)

The massive liquidity was not in these specific atomic markets, but in the broader questions (e.g., "Will Trump win the election?"). These broader markets are simply logical OR combinations of the atomic outcomes. In the configuration, the + symbol represents this OR relationship.

• Trump Wins Presidency (1+2): satisfied by Outcome 1 OR Outcome 2.
• Harris Wins Presidency (3+4): satisfied by Outcome 3 OR Outcome 4.
• Trump Wins Popular Vote (1+3): satisfied by Outcome 1 OR Outcome 3.
• Harris Wins Popular Vote (2+4): satisfied by Outcome 2 OR Outcome 4.

Visualizing the Overlap

The arbitrage opportunity exists because the price of a derived market (like "Trump Wins Presidency") should theoretically equal the sum of the prices of its components (Market 1 + Market 2). When they diverge, polyarb executes trades to profit from the difference.

graph TD
    subgraph "Atomic Outcomes (Mutually Exclusive)"
        O1("1: Rep Pres + Rep Pop"):::atomic
        O2("2: Rep Pres + Dem Pop"):::atomic
        O3("3: Dem Pres + Rep Pop"):::atomic
        O4("4: Dem Pres + Dem Pop"):::atomic
    end

    subgraph "Derived Markets (Liquid)"
        TP("Trump Wins Presidency (1 + 2)"):::derived
        HP("Harris Wins Presidency (3 + 4)"):::derived
        TV("Trump Wins Pop Vote (1 + 3)"):::derived
        HV("Harris Wins Pop Vote (2 + 4)"):::derived
    end

    %% Logic Connections
    O1 -->|Satisfies| TP
    O2 -->|Satisfies| TP
    
    O3 -->|Satisfies| HP
    O4 -->|Satisfies| HP

    O1 -->|Satisfies| TV
    O3 -->|Satisfies| TV
    
    O2 -->|Satisfies| HV
    O4 -->|Satisfies| HV

    %% Styling
    classDef atomic fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef derived fill:#ccddff,stroke:#333,stroke-width:2px;

Loading

Example Configuration:

Below is an example configuration for the 2024 election, showing how to define overlapping markets for arbitrage detection.

bundles:
  election_2024:
    expiration_date: "2024-11-05"
    events:
      - name: "Which party wins Presidency + Popular Vote?"
        markets:
          "1":
            question: "Will a Republican win the popular vote and the Presidency? "
            yes_id: "67648321332889562720702742465853245863647268672651902649177972067583993370930"
            no_id: "92848768921367210485187039202894189254214421377536495082521089096497548879926"
          "2":
            question: "Will a Democrat win the popular vote and a Republican win the Presidency?"
            yes_id: "79290738821633012952251194646343347843753407986785745774809464443278141510795"
            no_id: "77538554173896015114453401012117630452637136665613691153928336127167320141811"
          "3":
            question: "Will a Republican win the popular vote and a Democrat win the Presidency?"
            yes_id: "86476515438957907056315993820068995378660426416045749849962015285013351695183"
            no_id: "83494440765400389893993921944624001569626254294075627699017957553845440459741"
          "4":
            question: "Will a Democrat win the popular vote and the Presidency? "
            yes_id: "33573631646975967490303296373773410479817269960942179527425708594960263761938"
            no_id: "1245455071836736418858894114937610717733912531531312145552158827133486397267"
          "5":
            question: "Will a 3rd party candidate win the popular vote or the Presidency?"
            yes_id: "105188262404483697509467695252326324791411917773657147371863257988735030760167"
            no_id: "90045870183517702980104220495202846998800071123944874722260068936208046029630"

      - name: "Presidential Election Winner 2024"
        markets:
          "1+2":
            question: "Will Donald Trump win the 2024 US Presidential Election?"
            yes_id: "21742633143463906290569050155826241533067272736897614950488156847949938836455"
            no_id: "48331043336612883890938759509493159234755048973500640148014422747788308965732"
          "3+4":
            question: "Will Kamala Harris win the 2024 US Presidential Election?"
            yes_id: "69236923620077691027083946871148646972011131466059644796654161903044970987404"
            no_id: "87584955359245246404952128082451897287778571240979823316620093987046202296181"

      - name: "Popular Vote Winner 2024"
        markets:
          "1+3":
            question: "Will Donald Trump win the popular vote in the 2024 Presidential Election?"
            yes_id: "42699080635179861375280720242213672850141860123562672932351602811041149946128"
            no_id: "52646153159016006621189163812433115969858888637703551736022048114666679879653"
          "2+4":
            question: "Kamala Harris wins the popular vote?"
            yes_id: "21271000291843361249209065706097167029083067325856089903026951915683588703117"
            no_id: "43898019188443109254544011644141095748327433947336326565220861409147408981284"

Architecture

• src/api/: Interaction with Polymarket's CLOB (Central Limit Order Book) API.
• src/arbitrage/: Core logic for evaluating bundles and executing arbitrage strategies.
• src/wallet_manager.py: Handles wallet generation, funding, and Gnosis Safe proxy interactions.
• cli.py: The main entry point for all user interactions.

Disclaimer

This software is for educational purposes only. Trading prediction markets involves significant risk. The authors are not responsible for any financial losses incurred while using this tool. Use at your own risk.