Skip to content

feat: Add Auto-Claim, Dump Sniper, and Ladder Bot improvements #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
fciaf420 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat: Add Auto-Claim, Dump Sniper, and Ladder Bot improvements #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e6f830e
feat: Add ladder mode, position tracker, and simplify bot architecture
fciaf420 Dec 20, 2025
69cb1b9
feat: Add Auto-Claim and Dump Sniper features
fciaf420 Dec 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
238 changes: 238 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,238 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

PredictOS is an open-source AI-powered framework for deploying custom trading bots and analysis tools for prediction markets (Kalshi and Polymarket). The architecture is split into a Next.js frontend ("terminal") and Supabase Edge Functions backend running on Deno.

## Development Environment Setup

### Prerequisites
- Node.js v18+
- Docker (required for local Supabase)
- On Windows, use `npx supabase` instead of installing globally (npm global install not supported)

### Initial Setup

1. **Backend (Supabase):**
```bash
cd supabase
cp .env.example .env.local
# Edit .env.local with required API keys
npx supabase start
npx supabase status # Get credentials for frontend
```

2. **Start Edge Functions server (keep running):**
```bash
cd supabase
npx supabase functions serve --env-file .env.local
```

3. **Frontend (Terminal):**
```bash
cd terminal
npm install
cp .env.example .env
# Edit .env with credentials from `supabase status`
npm run dev
```

Access UI at http://localhost:3000

### Common Commands

**Backend:**
- `npx supabase start` - Start local Supabase stack
- `npx supabase stop` - Stop all services
- `npx supabase status` - Get local credentials
- `npx supabase functions serve --env-file .env.local` - Run Edge Functions
- `npx supabase db reset` - Reset database

**Frontend:**
- `npm run dev` - Start dev server (http://localhost:3000)
- `npm run build` - Production build
- `npm run lint` - Run ESLint

## Architecture

### Two-Tier Architecture

**Frontend (`terminal/`):**
- Next.js 14 with App Router
- React 18 client components
- TailwindCSS for styling
- Runs on port 3000

**Backend (`supabase/`):**
- Supabase Edge Functions (Deno runtime)
- Runs on port 54321
- API routes proxy to Edge Functions for security

### Key Architectural Patterns

1. **Edge Function Structure:**
- Each feature lives in `supabase/functions/<feature-name>/index.ts`
- Shared utilities in `supabase/functions/_shared/`
- Edge Functions export a `Deno.serve()` handler
- All use CORS headers for browser access

2. **Frontend-Backend Communication:**
- Frontend calls Next.js API routes (`terminal/src/app/api/`)
- API routes proxy to Supabase Edge Functions
- This keeps Supabase credentials server-side
- Example flow: UI → `/api/limit-order-bot` → Edge Function

3. **Shared Code Organization:**
```
supabase/functions/_shared/
├── ai/ # AI provider integrations (xAI, OpenAI)
├── dome/ # Dome API client (market data)
└── polymarket/ # Polymarket CLOB client
├── client.ts # Main client with order placement
├── types.ts # TypeScript definitions
└── utils.ts # Helper functions
```

## Environment Variables

### Backend (`supabase/.env.local`)

**Market Analysis Feature:**
- `DOME_API_KEY` - Required (https://dashboard.domeapi.io)
- `XAI_API_KEY` or `OPENAI_API_KEY` - At least one required

**Betting Bots Feature:**
- `POLYMARKET_WALLET_PRIVATE_KEY` - Your wallet private key (0x...)
- `POLYMARKET_PROXY_WALLET_ADDRESS` - Polymarket proxy wallet (0x...)

### Frontend (`terminal/.env`)

Get values from `npx supabase status`:
- `SUPABASE_URL` - Usually http://127.0.0.1:54321
- `SUPABASE_ANON_KEY` - Anonymous key from supabase status

Edge Function URLs (auto-configured but can override):
- `SUPABASE_EDGE_FUNCTION_ANALYZE_EVENT_MARKETS`
- `SUPABASE_EDGE_FUNCTION_BETTING_BOT`

## Feature-Specific Guidance

### Betting Bots (Polymarket Arbitrage)

**Bot Behavior:**
- Client-side timer runs in browser (not server-side)
- Interval: 15 minutes (`POLL_INTERVAL_MS = 15 * 60 * 1000`)
- Bot stops if user navigates away from `/betting-bots` page
- Component in `terminal/src/components/BettingBotTerminal.tsx`

**Important Limitations:**
1. **No order monitoring** - Bot only places orders, doesn't track fills
2. **No auto-cancellation** - Unfilled orders remain on Polymarket
3. **No profit claiming** - User must manually claim winnings on Polymarket
4. **No partial fill protection** - If only one side fills, user has directional exposure

**Order Placement:**
- Uses Polymarket CLOB client (`@polymarket/clob-client`)
- Places GTC (Good Till Cancelled) limit orders
- Default price: 0.48 (48 cents)
- Minimum order size: $3 (Polymarket requires 5+ shares)
- Orders placed via `PolymarketClient.placeStraddleOrders()`

**Key Files:**
- `supabase/functions/polymarket-up-down-15-markets-limit-order-bot/index.ts`
- `supabase/functions/_shared/polymarket/client.ts`
- `terminal/src/components/BettingBotTerminal.tsx`
- `terminal/src/app/api/limit-order-bot/route.ts`

### Market Analysis

**Integration Points:**
- Dome API for market data (Kalshi + Polymarket)
- xAI Grok or OpenAI for analysis
- Edge Function: `analyze-event-markets`

## TypeScript Patterns

**Edge Functions (Deno):**
- Use `// @ts-ignore` for Deno npm imports
- Access env vars via `Deno.env.get()`
- Import npm packages with `npm:package-name@version`

**Frontend:**
- Client components: `"use client"` directive
- Type definitions in `terminal/src/types/`
- Shared types between frontend and Edge Functions duplicated

## Critical Implementation Details

### Polymarket Integration

1. **Client Initialization:**
```typescript
// Creates CLOB client with API credentials
const client = new ClobClient(host, chainId, signer, creds, signatureType, proxyAddress)
```

2. **Order Placement:**
- Price in decimal (0.48 = 48%)
- Size must be integer shares
- Uses `OrderType.GTC` (Good Till Cancelled)
- Default tick size: "0.01"

3. **Market Slugs:**
- Format: `{asset}-{timestamp}` (e.g., "btc-1234567890")
- Timestamp is Unix epoch rounded to 15-min intervals
- Function: `buildMarketSlug()` in `_shared/polymarket/utils.ts`

### Supabase Local Development

- All services run in Docker containers
- Default ports:
- API/Functions: 54321
- Database: 54322
- Studio: 54323
- Inbucket (email): 54324
- Config in `supabase/config.toml`
- Uses Deno 2.x for Edge Runtime

## Adding New Features

1. Create Edge Function: `supabase/functions/<feature-name>/index.ts`
2. Add shared utilities to `supabase/functions/_shared/`
3. Create Next.js API route: `terminal/src/app/api/<feature>/route.ts`
4. Add frontend components in `terminal/src/components/`
5. Add types to `terminal/src/types/`
6. Update environment variable templates (`.env.example`)

## Testing Workflow

**Local Development:**
1. Start Supabase: `npx supabase start`
2. Start Edge Functions: `npx supabase functions serve --env-file .env.local`
3. Start frontend: `npm run dev` (in terminal/)
4. Access: http://localhost:3000

**Testing Betting Bot:**
- Navigate to http://localhost:3000/betting-bots
- Bot requires USDC balance on Polymarket
- Monitor Polymarket UI for order fills
- Positions must be claimed manually on Polymarket

## Known Issues & Gotchas

1. **Windows Users:** Must use `npx supabase` - global npm install fails
2. **Browser Tab Required:** Betting bot stops when tab is closed or navigated away
3. **Cold Starts:** Edge Functions may timeout on first call (API route has retry logic)
4. **No Order Tracking:** Bot doesn't monitor or cancel orders after placement
5. **Manual Claiming:** Winnings must be claimed manually on Polymarket website
6. **Partial Fill Risk:** No protection if only one side of arbitrage fills

## Security Notes

- Never commit `.env.local` or `.env` files
- Private keys stored in `supabase/.env.local` (backend only)
- Frontend only receives Supabase public keys
- Use dedicated wallet with limited funds for bot trading
- `.gitignore` includes all environment files
36 changes: 36 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,7 @@ A key feature driving adoption is the ability to **stake $PREDICT for attractive
|---------|--------|-------------|-------------|
| **AI Market Analysis** | ✅ Released | Paste a Kalshi or Polymarket URL and get instant AI-powered analysis with probability estimates, confidence scores, and trading recommendations | [📖 Setup Guide](docs/features/market-analysis.md) |
| **Betting Bots** | ✅ Released | Polymarket 15 Minute Up/Down Arbitrage Bot (more bots coming) | [📖 Setup Guide](docs/features/betting-bots.md) |
| **Auto-Claim** | ✅ Released | Automatically claim winning positions from resolved Polymarket markets | [📖 Setup Guide](docs/features/auto-claim.md) |

## 🔮 Coming Soon

Expand Down Expand Up @@ -158,8 +159,25 @@ Example for Betting Bots:
```env
POLYMARKET_WALLET_PRIVATE_KEY=0x... # Your wallet private key
POLYMARKET_PROXY_WALLET_ADDRESS=0x... # Your Polymarket proxy wallet

# Pre-derived API credentials (REQUIRED to avoid CPU timeout errors)
POLYMARKET_API_KEY=...
POLYMARKET_API_SECRET=...
POLYMARKET_API_PASSPHRASE=...
```

> ⚠️ **Important:** The API credentials are derived from your private key and are required to avoid CPU timeout errors. After adding your `POLYMARKET_WALLET_PRIVATE_KEY` to `.env.local`, run this script to auto-generate and populate the credentials:
>
> ```bash
> cd terminal
> npm install # First time only
> node ../scripts/derive-polymarket-creds.js
> ```
>
> The script will automatically update your `supabase/.env.local` file.
>
> **Re-run this script if you change wallets** - each wallet has unique API credentials.

> 💡 **Note:** See the setup guides linked above for detailed instructions on obtaining each API key and configuration.

Start the Supabase services:
Expand Down Expand Up @@ -262,6 +280,24 @@ Your PredictOS terminal will be running at [http://localhost:3000](http://localh
</tr>
</table>

## 👥 Contributors

<table>
<tr>
<td width="100" align="center">
<a href="https://x.com/mininghelium1">
<img src="https://pbs.twimg.com/profile_images/1853296548395520000/MWnmY-Bt_400x400.jpg" width="60" height="60" style="border-radius: 50%;" alt="@mininghelium1" />
<br />
<sub><b>@mininghelium1</b></sub>
</a>
</td>
<td>
<strong>Ladder Bot & Dump Sniper</strong><br/>
Developer of the Polymarket 15-minute up/down betting bots. Built the Ladder Mode arbitrage strategy with exponential tapering and the Dump Sniper for catching volatility dumps with real-time WebSocket price monitoring, auto-hedging, and USD profit tracking.
</td>
</tr>
</table>

## 💪 Contributing

We welcome contributions from the community! Here's how you can help:
Expand Down
Loading