# PredCopy docs

A guide for users and LLM agents on how to use PredCopy to copy-trade Polymarket whales.

## What PredCopy does

PredCopy lets you watch any Polymarket wallet (a "whale") and automatically mirror its BUY trades in your own Polymarket account. It runs a server-side engine that polls each watched whale every few seconds via Polymarket's official `/activity` feed, dedupes new trades, and places matching orders.

Two modes:
- **Paper trading**: free, default. Every account starts with $1,000 of virtual capital. Orders are simulated, P&L is recorded against current market prices.
- **Live trading**: real orders placed via your own Polymarket API key. Requires Pro ($29/mo or $99/year) and your Polymarket API credentials.

## Finding good whales

1. Open the [leaderboard](https://predcopy.com/leaderboard). Traders are ranked by PolyCopy score, a composite of P&L, win rate, market diversity, and recent activity.
2. Filter by category: `/leaderboard/{politics, crypto, sports, pop-culture, elections, tech, ...}`.
3. Skip wallets flagged "Market maker" on the wallet card. Their fills are sub-cent LP dust, copying them via taker orders loses money on the spread.
4. Skip "Dormant" or "No BUY in 7d+" wallets — copy engines need fresh BUY signals to mirror.

Each wallet's profile page (`/trader/{address}`) shows full position history, category breakdown, win rate over time, and a ScoreRing visualizing the PolyCopy components.

## Copying a wallet

After signing in:
1. Go to `/dashboard`.
2. Paste a Polymarket wallet address (0x…) in the "Add wallet" form.
3. Click "Copy wallet" on the wallet card.
4. In the modal: pick paper or live, bet size %, max bet, and optional take-profit / stop-loss.
5. From this point, every BUY the whale makes that passes the filters fires a matching paper order against your $1,000 virtual book.

The watcher applies two filters before emitting a trade event:
- Notional ≥ $5 (drops dust LP fills)
- Price ≥ 1¢ (drops basically-resolved markets)
And throttles same-(market, side) emissions to 1 per 5 minutes.

## Baskets

Group multiple wallets and copy them as a single bundle with shared settings:
1. `/dashboard` → "New Basket".
2. Paste wallet addresses (one per line).
3. Click "Copy basket" to apply the same settings to every wallet in the basket.

## Performance

`/dashboard/pnl` shows:
- 4-tile summary: total P&L (realized + unrealized), open positions ($X deployed), portfolio value, closed trades count.
- Open positions table: each position with entry price vs current price and unrealized P&L.
- Per-wallet closed-trade attribution.
- Filter by wallet or basket.

Paper accounts show a context strip: starting balance ($1,000), cash available, deployed.

## For AI agents

PredCopy is designed to be readable by LLM agents.

- The leaderboard, market, event, and trader pages all carry structured `<JsonLd>` payloads (schema.org ItemList / WebPage) for crawlers.
- `/llms.txt` is a curated navigation hub.
- Every page renders with Tailwind and predictable DOM. A scrape-based agent can extract trader addresses, scores, and market prices reliably.

The cleanest agent workflow:

1. **Authenticate**: the user generates a personal API key at `/dashboard/settings` (one-click, shown once). The agent stores it in its secrets config.
2. **Discover**: agent fetches `/leaderboard` and `/best-traders/{tag}` to surface candidates.
3. **Verify**: pulls `/trader/{address}` for each candidate to confirm score, win rate, and that the wallet hasn't been flagged as market maker or dormant.
4. **Act**: `POST /api/wallets` to add the wallet, then `POST /api/copy` to start copying it with the desired settings.

All write endpoints accept `Authorization: Bearer pc_xxx` as an alternative to the dashboard's session cookie. The same routes the dashboard uses are open to agents with the user's key.

### Example: full agent flow

```bash
# Add a wallet to the user's watchlist
curl -X POST https://predcopy.com/api/wallets \
  -H "Authorization: Bearer pc_xxx" \
  -H "Content-Type: application/json" \
  -d '{"address":"0xfedc381bf3fb5d20433bb4a0216b15dbbc5c6398","label":"Politics whale"}'

# Start copying it in paper mode at 5% bet size, max $20 per trade
curl -X POST https://predcopy.com/api/copy \
  -H "Authorization: Bearer pc_xxx" \
  -H "Content-Type: application/json" \
  -d '{"walletId":"<id from previous response>","action":"start","settings":{"isPaper":true,"betPct":0.05,"maxBetUsd":20}}'

# Read current paper positions + unrealized P&L
curl https://predcopy.com/api/pnl/positions \
  -H "Authorization: Bearer pc_xxx"
```

## Pricing

- **Free**: 1 watched wallet, view-only.
- **Pro $29/mo**: unlimited wallets, paper + live trading.
- **Pro $99/year**: same as monthly, save 72%.
- **Lifetime €200**: one-time payment, all features forever.

## Support

Hit `/dashboard/support` to message the team. Replies land at your account email within a business day.

## Source URLs

- Site: https://predcopy.com
- llms.txt: https://predcopy.com/llms.txt
- This doc: https://predcopy.com/docs.md
- Sitemap: https://predcopy.com/sitemap.xml