arbibot

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# ArbiBot - Sports & Esports Arbitrage Bot for Kalshi & Polymarket

An automated arbitrage bot focused on **sports and esports markets** that identifies and executes profit opportunities between Kalshi and Polymarket.

## 🎮⚽ Sports & Esports Focus

This bot **exclusively monitors sports and esports markets** for the following:

**Esports:**
- **CS2** (Counter-Strike 2)
- **League of Legends**
- **Valorant**
- **Dota 2**
- **Call of Duty** (CoD, Warzone)

**Traditional Sports:**
- **NBA** (Basketball)
- **Soccer** (Football, Premier League, UEFA, Champions League)
- **NFL** (American Football)
- **Tennis** (ATP, WTA, Grand Slams)
- **MMA** (UFC, Bellator)

## Overview

ArbiBot continuously monitors sports and esports markets on both Kalshi and Polymarket to identify arbitrage opportunities. The bot:

- Fetches active sports/esports markets from both platforms (live and upcoming matches/games)
- Filters for high-liquidity markets (minimum $100 volume)
- Matches similar markets across platforms using intelligent name matching
- Detects arbitrage opportunities using proven strategies
- Executes trades automatically (when enabled)
- Monitors active positions and cancels stale orders
- Tracks profit and loss
- **Portfolio Allocation**: 70% for near-term markets (<24hrs), 30% for future markets

## Features

- **🎮⚽ Sports & Esports Focus**: Monitors esports (CS2, LoL, Valorant, Dota 2, CoD) and traditional sports (NBA, Soccer, NFL, Tennis, MMA)
- **💧 Liquidity Filtering**: Only trades on markets with $100+ volume for real execution capability
- **📊 Portfolio Allocation Strategy**:
  - 70% allocated to near-term markets (live or resolving within 24 hours)
  - 30% allocated to future markets (higher profit threshold required)
  - Prevents liquidity from getting locked up long-term
- **Cross-Platform Arbitrage**: Only looks for opportunities between Kalshi and Polymarket (not within a single platform)
- **Valid Arbitrage Strategy**:
  - Buy opposing outcomes (YES + NO) across platforms
  - Total cost < $1.00 guarantees profit (one outcome must pay $1.00)
  - No existing positions required
- **Paper Trading Mode**: Test strategies with simulated money before risking real capital
- **Telegram Notifications**: Real-time alerts for opportunities and hourly performance summaries
- **Intelligent Market Matching**: Recognizes team/player names and match formats across platforms
- **Risk Management**: Configurable profit thresholds and position size limits
- **Order Management**: Automatically cancels stale orders to prevent losses
- **Profit Tracking**: Real-time tracking of executed trades and profits

## Installation

1. Clone the repository:
```bash
git clone <repository-url>
cd ArbiBot
```

2. Install dependencies:
```bash
npm install
```

3. Configure environment variables:
```bash
cp .env.example .env
```

Edit `.env` with your API credentials and preferences.

## Quick Start (Paper Trading)

The safest way to test ArbiBot is with paper trading mode:

1. Install dependencies:
```bash
npm install
```

2. Copy the example configuration:
```bash
cp .env.example .env
```

3. Set up Telegram notifications (optional but recommended):
   - See [TELEGRAM_SETUP.md](https://github.com/axwelbrand-byte/arbibot/blob/HEAD/TELEGRAM_SETUP.md) for detailed instructions
   - Or skip this step to run without notifications

4. Edit `.env` and set:
```env
PAPER_TRADING_MODE=true
STARTING_BALANCE=1000
ENABLE_TELEGRAM_NOTIFICATIONS=true  # if you set up Telegram
TELEGRAM_BOT_TOKEN=your_bot_token    # from @BotFather
TELEGRAM_CHAT_ID=your_chat_id        # your Telegram user ID
```

5. Run the bot:
```bash
npm run dev
```

6. Monitor results in console and Telegram!

## Configuration

Create a `.env` file with the following variables:

```env
# Kalshi API Configuration
KALSHI_API_KEY=your_kalshi_api_key_here
KALSHI_PRIVATE_KEY=your_kalshi_private_key_here
KALSHI_API_URL=https://api.elections.kalshi.com/trade-api/v2

# Polymarket API Configuration
POLYMARKET_API_KEY=your_polymarket_api_key_here
POLYMARKET_PRIVATE_KEY=your_polymarket_private_key_here
POLYMARKET_API_URL=https://clob.polymarket.com

# Bot Configuration
MIN_PROFIT_THRESHOLD=0.02        # Minimum 2% profit required
MAX_POSITION_SIZE=100            # Maximum $100 per trade
CHECK_INTERVAL_MS=5000           # Check every 5 seconds
ENABLE_TRADING=false             # Set to true to execute real trades
PAPER_TRADING_MODE=true          # Use simulated money for testing
STARTING_BALANCE=1000            # Starting balance for paper trading

# Telegram Configuration
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here
ENABLE_TELEGRAM_NOTIFICATIONS=true
HOURLY_SUMMARY_ENABLED=true

# Logging
LOG_LEVEL=info                   # Log level: debug, info, warn, error
```

### Configuration Options

**Bot Settings:**
- `MIN_PROFIT_THRESHOLD`: Minimum profit percentage required to execute a trade (e.g., 0.02 = 2%)
- `MAX_POSITION_SIZE`: Maximum amount to invest in a single arbitrage opportunity
- `CHECK_INTERVAL_MS`: How often to scan for opportunities (in milliseconds)
- `ENABLE_TRADING`: Set to `false` for dry-run mode, `true` to execute real trades
- `LOG_LEVEL`: Verbosity of logging (debug, info, warn, error)

**Paper Trading Settings:**
- `PAPER_TRADING_MODE`: Set to `true` to use simulated money (recommended for testing)
- `STARTING_BALANCE`: Starting balance for paper trading (e.g., 1000 = $1,000)

**Telegram Settings:**
- `TELEGRAM_BOT_TOKEN`: Your Telegram bot token from @BotFather
- `TELEGRAM_CHAT_ID`: Your Telegram user ID (see [TELEGRAM_SETUP.md](https://github.com/axwelbrand-byte/arbibot/blob/HEAD/TELEGRAM_SETUP.md))
- `ENABLE_TELEGRAM_NOTIFICATIONS`: Set to `true` to receive notifications
- `HOURLY_SUMMARY_ENABLED`: Set to `true` to receive hourly performance summaries

## Getting API Keys

### Kalshi

1. Sign up at [kalshi.com](https://kalshi.com)
2. Navigate to Profile Settings
3. Click "Create New API Key"
4. Save your API key and private key

### Polymarket

1. Sign up at [polymarket.com](https://polymarket.com)
2. Access the API documentation to generate credentials
3. Save your API key and private key

## Usage

### Development Mode

Run the bot with hot-reloading:

```bash
npm run dev
```

### Production Mode

Build and run the bot:

```bash
npm run build
npm start
```

### Watch Mode

Compile TypeScript in watch mode:

```bash
npm run watch
```

## How It Works

### 1. Market Fetching

The bot fetches active markets from both Kalshi and Polymarket APIs.

### 2. Market Matching

Markets are matched across platforms using:
- String similarity (Levenshtein distance)
- Key phrase matching
- Normalization of market names

### 3. Arbitrage Detection

The bot checks for **valid arbitrage opportunities** using opposing outcomes:

1. **Buy YES on Platform A + Buy NO on Platform B**
   - If total cost < $1.00, guaranteed profit (one outcome pays $1.00)
   - Example: Buy Team Liquid YES @ $0.45 + Buy Team Liquid NO @ $0.48 = $0.93 cost → $0.07 profit

2. **Buy NO on Platform A + Buy YES on Platform B**
   - Same strategy, reversed order
   - No existing positions required

**Note**: The bot does NOT use buy/sell strategies (e.g., "Buy YES then Sell YES") because you cannot sell shares you don't own. Only buying opposing outcomes guarantees profit without requiring pre-existing positions.

### 4. Order Execution

**Paper Trading Mode:**
- Simulates trades with virtual money
- Tracks simulated profit/loss
- 95% success rate with realistic slippage (90-100% of expected profit)
- Trades "fill" after 10-30 seconds
- Sends notifications for each trade

**Live Trading Mode:**
When an opportunity is found and trading is enabled:
1. Places buy order on the first platform
2. Places sell order on the second platform
3. If either order fails, cancels the successful order
4. Tracks the arbitrage position

### 5. Notifications & Monitoring

**Telegram Notifications (if enabled):**
- Startup notification
- Real-time arbitrage opportunity alerts
- Trade execution notifications
- Trade result notifications (success/failure)
- Hourly performance summaries
- Error notifications

**Order Monitoring (live trading):**
The bot continuously monitors active orders and:
- Updates order statuses
- Cancels stale orders (> 1 minute old)
- Prevents losses from incomplete arbitrages

## Project Structure

```
ArbiBot/
├── src/
│   ├── clients/
│   │   ├── kalshi.ts             # Kalshi API client
│   │   └── polymarket.ts         # Polymarket API client
│   ├── services/
│   │   ├── marketMatcher.ts      # Market matching logic
│   │   ├── arbitrageDetector.ts  # Arbitrage detection
│   │   ├── orderManager.ts       # Order placement and management
│   │   ├── paperTrading.ts       # Paper trading simulation
│   │   └── telegramNotifier.ts   # Telegram notifications
│   ├── types/
│   │   └── index.ts              # TypeScript type definitions
│   ├── utils/
│   │   ├── config.ts          # Configuration loader
│   │   └── logger.ts          # Logging utility
│   ├── bot.ts                 # Main bot orchestrator
│   └── index.ts               # Entry point
├── .env.example               # Example environment variables
├── .gitignore
├── package.json
├── tsconfig.json
├── TELEGRAM_SETUP.md          # Telegram bot setup guide
└── README.md
```

## Safety Features

1. **Paper Trading Mode**: Test with simulated money before risking real capital
2. **Real-time Notifications**: Get instant alerts via Telegram for every opportunity
3. **Profit Threshold**: Only execute trades above minimum profit
4. **Position Limits**: Cap maximum investment per trade
5. **Stale Order Cancellation**: Automatically cancel orders that don't fill quickly
6. **Error Handling**: Robust error handling and logging
7. **Graceful Shutdown**: Proper cleanup on SIGINT/SIGTERM

## Logging

Logs are written to:
- Console (with colors)
- `combined.log` (all logs)
- `error.log` (errors only)

## Risk Disclaimer

**USE AT YOUR OWN RISK**

This bot involves real financial transactions. There are risks including:
- API failures or delays
- Market volatility
- Partial fills
- Slippage
- Platform-specific risks

Always:
- Start with small position sizes
- Use dry-run mode first
- Monitor the bot closely
- Never invest more than you can afford to lose

## Troubleshooting

### No markets found

- Check your API keys are correct
- Verify API endpoints are accessible
- Check rate limits on the platforms

### No matching markets

- The platforms may not have overlapping markets
- Adjust the similarity threshold in `marketMatcher.ts`

### Orders not executing

- Verify `ENABLE_TRADING=true` in `.env`
- Check you have sufficient balance on both platforms
- Review logs for API errors

## Future Improvements

- WebSocket support for real-time price updates
- More sophisticated market matching algorithms
- Multi-leg arbitrage strategies
- Portfolio optimization
- Backtesting framework
- Web dashboard for monitoring

## License

MIT

## Contributing

Contributions are welcome! Please open an issue or pull request.

## API Documentation

- [Kalshi API Docs](https://docs.kalshi.com/welcome)
- [Polymarket API Docs](https://docs.polymarket.com)

## Sources

- [Introduction - API Documentation - Kalshi](https://docs.kalshi.com/welcome)
- [Kalshi API | Kalshi Help Center](https://help.kalshi.com/kalshi-api)
- [Kalshi API: The Complete Developer's Guide | Zuplo Learning Center](https://zuplo.com/learning-center/kalshi-api)

ArbiBot - Sports & Esports Arbitrage Bot for Kalshi & Polymarket

An automated arbitrage bot focused on sports and esports markets that identifies and executes profit opportunities between Kalshi and Polymarket.

🎮⚽ Sports & Esports Focus

This bot exclusively monitors sports and esports markets for the following:

Esports:

CS2 (Counter-Strike 2)
League of Legends
Valorant
Dota 2
Call of Duty (CoD, Warzone)

Traditional Sports:

NBA (Basketball)
Soccer (Football, Premier League, UEFA, Champions League)
NFL (American Football)
Tennis (ATP, WTA, Grand Slams)
MMA (UFC, Bellator)

Overview

ArbiBot continuously monitors sports and esports markets on both Kalshi and Polymarket to identify arbitrage opportunities. The bot:

Fetches active sports/esports markets from both platforms (live and upcoming matches/games)
Filters for high-liquidity markets (minimum $100 volume)
Matches similar markets across platforms using intelligent name matching
Detects arbitrage opportunities using proven strategies
Executes trades automatically (when enabled)
Monitors active positions and cancels stale orders
Tracks profit and loss
Portfolio Allocation: 70% for near-term markets (<24hrs), 30% for future markets

Features

🎮⚽ Sports & Esports Focus: Monitors esports (CS2, LoL, Valorant, Dota 2, CoD) and traditional sports (NBA, Soccer, NFL, Tennis, MMA)
💧 Liquidity Filtering: Only trades on markets with $100+ volume for real execution capability
📊 Portfolio Allocation Strategy:
- 70% allocated to near-term markets (live or resolving within 24 hours)
- 30% allocated to future markets (higher profit threshold required)
- Prevents liquidity from getting locked up long-term
Cross-Platform Arbitrage: Only looks for opportunities between Kalshi and Polymarket (not within a single platform)
Valid Arbitrage Strategy:
- Buy opposing outcomes (YES + NO) across platforms
- Total cost < $1.00 guarantees profit (one outcome must pay $1.00)
- No existing positions required
Paper Trading Mode: Test strategies with simulated money before risking real capital
Telegram Notifications: Real-time alerts for opportunities and hourly performance summaries
Intelligent Market Matching: Recognizes team/player names and match formats across platforms
Risk Management: Configurable profit thresholds and position size limits
Order Management: Automatically cancels stale orders to prevent losses
Profit Tracking: Real-time tracking of executed trades and profits

Installation

Clone the repository:

git clone <repository-url>
cd ArbiBot

Install dependencies:

npm install

Configure environment variables:

cp .env.example .env

Edit .env with your API credentials and preferences.

Quick Start (Paper Trading)

The safest way to test ArbiBot is with paper trading mode:

Install dependencies:

npm install

Copy the example configuration:

cp .env.example .env

Set up Telegram notifications (optional but recommended):
- See TELEGRAM_SETUP.md for detailed instructions
- Or skip this step to run without notifications
Edit .env and set:

PAPER_TRADING_MODE=true
STARTING_BALANCE=1000
ENABLE_TELEGRAM_NOTIFICATIONS=true  # if you set up Telegram
TELEGRAM_BOT_TOKEN=your_bot_token    # from @BotFather
TELEGRAM_CHAT_ID=your_chat_id        # your Telegram user ID

Run the bot:

npm run dev

Monitor results in console and Telegram!

Configuration

Create a .env file with the following variables:

# Kalshi API Configuration
KALSHI_API_KEY=your_kalshi_api_key_here
KALSHI_PRIVATE_KEY=your_kalshi_private_key_here
KALSHI_API_URL=https://api.elections.kalshi.com/trade-api/v2

# Polymarket API Configuration
POLYMARKET_API_KEY=your_polymarket_api_key_here
POLYMARKET_PRIVATE_KEY=your_polymarket_private_key_here
POLYMARKET_API_URL=https://clob.polymarket.com

# Bot Configuration
MIN_PROFIT_THRESHOLD=0.02        # Minimum 2% profit required
MAX_POSITION_SIZE=100            # Maximum $100 per trade
CHECK_INTERVAL_MS=5000           # Check every 5 seconds
ENABLE_TRADING=false             # Set to true to execute real trades
PAPER_TRADING_MODE=true          # Use simulated money for testing
STARTING_BALANCE=1000            # Starting balance for paper trading

# Telegram Configuration
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here
ENABLE_TELEGRAM_NOTIFICATIONS=true
HOURLY_SUMMARY_ENABLED=true

# Logging
LOG_LEVEL=info                   # Log level: debug, info, warn, error

Configuration Options

Bot Settings:

MIN_PROFIT_THRESHOLD: Minimum profit percentage required to execute a trade (e.g., 0.02 = 2%)
MAX_POSITION_SIZE: Maximum amount to invest in a single arbitrage opportunity
CHECK_INTERVAL_MS: How often to scan for opportunities (in milliseconds)
ENABLE_TRADING: Set to false for dry-run mode, true to execute real trades
LOG_LEVEL: Verbosity of logging (debug, info, warn, error)

Paper Trading Settings:

PAPER_TRADING_MODE: Set to true to use simulated money (recommended for testing)
STARTING_BALANCE: Starting balance for paper trading (e.g., 1000 = $1,000)

Telegram Settings:

TELEGRAM_BOT_TOKEN: Your Telegram bot token from @BotFather
TELEGRAM_CHAT_ID: Your Telegram user ID (see TELEGRAM_SETUP.md)
ENABLE_TELEGRAM_NOTIFICATIONS: Set to true to receive notifications
HOURLY_SUMMARY_ENABLED: Set to true to receive hourly performance summaries

Getting API Keys

Kalshi

Sign up at kalshi.com
Navigate to Profile Settings
Click "Create New API Key"
Save your API key and private key

Polymarket

Sign up at polymarket.com
Access the API documentation to generate credentials
Save your API key and private key

Usage

Development Mode

Run the bot with hot-reloading:

npm run dev

Production Mode

Build and run the bot:

npm run build
npm start

Watch Mode

Compile TypeScript in watch mode:

npm run watch

How It Works

1. Market Fetching

The bot fetches active markets from both Kalshi and Polymarket APIs.

2. Market Matching

Markets are matched across platforms using:

String similarity (Levenshtein distance)
Key phrase matching
Normalization of market names

3. Arbitrage Detection

The bot checks for valid arbitrage opportunities using opposing outcomes:

Buy YES on Platform A + Buy NO on Platform B
- If total cost < $1.00, guaranteed profit (one outcome pays $1.00)
- Example: Buy Team Liquid YES @ $0.45 + Buy Team Liquid NO @ $0.48 = $0.93 cost → $0.07 profit
Buy NO on Platform A + Buy YES on Platform B
- Same strategy, reversed order
- No existing positions required

Note: The bot does NOT use buy/sell strategies (e.g., "Buy YES then Sell YES") because you cannot sell shares you don't own. Only buying opposing outcomes guarantees profit without requiring pre-existing positions.

4. Order Execution

Paper Trading Mode:

Simulates trades with virtual money
Tracks simulated profit/loss
95% success rate with realistic slippage (90-100% of expected profit)
Trades "fill" after 10-30 seconds
Sends notifications for each trade

Live Trading Mode: When an opportunity is found and trading is enabled:

Places buy order on the first platform
Places sell order on the second platform
If either order fails, cancels the successful order
Tracks the arbitrage position

5. Notifications & Monitoring

Telegram Notifications (if enabled):

Startup notification
Real-time arbitrage opportunity alerts
Trade execution notifications
Trade result notifications (success/failure)
Hourly performance summaries
Error notifications

Order Monitoring (live trading): The bot continuously monitors active orders and:

Updates order statuses
Cancels stale orders (> 1 minute old)
Prevents losses from incomplete arbitrages

Project Structure

ArbiBot/
├── src/
│   ├── clients/
│   │   ├── kalshi.ts             # Kalshi API client
│   │   └── polymarket.ts         # Polymarket API client
│   ├── services/
│   │   ├── marketMatcher.ts      # Market matching logic
│   │   ├── arbitrageDetector.ts  # Arbitrage detection
│   │   ├── orderManager.ts       # Order placement and management
│   │   ├── paperTrading.ts       # Paper trading simulation
│   │   └── telegramNotifier.ts   # Telegram notifications
│   ├── types/
│   │   └── index.ts              # TypeScript type definitions
│   ├── utils/
│   │   ├── config.ts          # Configuration loader
│   │   └── logger.ts          # Logging utility
│   ├── bot.ts                 # Main bot orchestrator
│   └── index.ts               # Entry point
├── .env.example               # Example environment variables
├── .gitignore
├── package.json
├── tsconfig.json
├── TELEGRAM_SETUP.md          # Telegram bot setup guide
└── README.md

Safety Features

Paper Trading Mode: Test with simulated money before risking real capital
Real-time Notifications: Get instant alerts via Telegram for every opportunity
Profit Threshold: Only execute trades above minimum profit
Position Limits: Cap maximum investment per trade
Stale Order Cancellation: Automatically cancel orders that don't fill quickly
Error Handling: Robust error handling and logging
Graceful Shutdown: Proper cleanup on SIGINT/SIGTERM

Logging

Logs are written to:

Console (with colors)
combined.log (all logs)
error.log (errors only)

Risk Disclaimer

USE AT YOUR OWN RISK

This bot involves real financial transactions. There are risks including:

API failures or delays
Market volatility
Partial fills
Slippage
Platform-specific risks

Always:

Start with small position sizes
Use dry-run mode first
Monitor the bot closely
Never invest more than you can afford to lose

Troubleshooting

No markets found

Check your API keys are correct
Verify API endpoints are accessible
Check rate limits on the platforms

No matching markets

The platforms may not have overlapping markets
Adjust the similarity threshold in marketMatcher.ts

Orders not executing

Verify ENABLE_TRADING=true in .env
Check you have sufficient balance on both platforms
Review logs for API errors

Future Improvements

WebSocket support for real-time price updates
More sophisticated market matching algorithms
Multi-leg arbitrage strategies
Portfolio optimization
Backtesting framework
Web dashboard for monitoring