Polybot

Polymarket from your terminal.

Mirror the smartest wallets, run autonomous strategies, and place orders with one command. No dashboard, no signup, no config files.

30-second start · Commands · SDK · AI agents · Architecture

⚡ 30-second start

npm i -g polybot     # installs and prompts for your wallet key once
polybot scan         # see trending markets
polybot copy --target 0xWhale --size-multiplier 0.05   # paper-trade by default

That's it. No .env to edit, no database to set up, no account to create.

The first time you install Polybot it will ask for your Polygon wallet private key. The key is encrypted before it leaves your machine and stored in a hosted vault — Polybot can sign Polymarket orders for you, but the plaintext key is never written to disk and never logged.

Paper-trading is on by default. Pass --live to commit real USDC.

🧰 Commands

Every command supports --live to commit real USDC. Without it you're in paper mode.

Wallet modes

By default Polybot signs as a Polygon EOA. For Polymarket Magic / proxy wallets or Gnosis Safe, set:

POLY_FUNDER_ADDRESS=0xYourPolymarketProxy
POLY_SIGNATURE_TYPE=1     # 1 = proxy, 2 = safe, 0 = EOA (default)

🧠 Built-in strategies

polybot auto runs any combination of:

• arbitrage — binary markets where YES + NO < 1; closes the gap at maker prices.
• mean_reversion — fades aggressive moves on liquid markets back toward time-weighted average.
• momentum — rides trending markets with trailing stops.
• endgame — buys deep ITM probability when expiry is close and the market is mispricing tail risk.

Combine them: polybot auto --strategies arbitrage,momentum --per-trade 25 --live.

Every signal goes through the risk engine before execution: position caps, daily loss limits, slippage guards, market black/whitelists. Paper mode is enforced at the engine level — strategies cannot bypass it.

🪞 Copy trading

polybot copy --target 0xWhale --size-multiplier 0.05 --max-trade 50 --live

Polybot watches the target wallet on the Polymarket Data API and mirrors every entry/exit at a fraction of the original size. Per-market cooldowns and slippage guards prevent you from chasing a moving price.

Find good targets with:

polybot scan --limit 50

Or browse the Polymarket leaderboard.

📦 SDK

Embed Polybot in your own backend, AI agent, or CI job:

npm i @polybot/sdk

import { Polybot } from "@polybot/sdk";

const bot = await Polybot.create({
  privateKey: process.env.PRIVATE_KEY!,
  paperTrading: false,
});

// Manual order
await bot.trade({
  market: "trump-2028",
  side: "BUY",
  outcome: "YES",
  usdcSize: 25,
});

// Mirror a whale
bot.copy.addTarget({
  wallet: "0xWhale",
  sizeMultiplier: 0.05,
  maxTradeUsd: 50,
});
await bot.copy.start();

// Or run autonomous strategies
await bot.auto.start({ strategies: ["arbitrage", "endgame"], perTradeUsd: 25 });

Full API: packages/sdk/README.md.

🤖 AI agents

Polybot is the cleanest Polymarket layer for any LLM agent — Claude, GPT, Gemini, Vercel AI SDK, MCP — because everything important is one TypeScript call away:

import { Polybot } from "@polybot/sdk";

const bot = await Polybot.create({ privateKey, paperTrading: true });

// Tool 1: market discovery
const trending = await bot.trendingMarkets(25);

// Tool 2: live quote
const market = await bot.findMarket("trump-2028");

// Tool 3: place an order (paper or live)
await bot.trade({ market: market.slug!, side: "BUY", outcome: "YES", usdcSize: 25 });

Wire those into your agent's tool list and you have a fully-functioning Polymarket trader. No browser automation. No screen scraping. Direct REST + EIP-712 signing. The risk engine still gates every order, so a misbehaving agent cannot bypass position caps or daily loss limits.

🏗 Architecture

polybot/
└── packages/
    ├── cli/        # 📦 polybot — the npm CLI you install
    ├── sdk/        # 📦 @polybot/sdk — embed Polybot in any Node app
    ├── core/       # Gamma, CLOB v2, Data API, WebSocket clients
    └── engine/     # RiskManager, WalletWatcher, strategies

Four packages, no backend services to run, no database to provision. Every command goes through the same code path — CLI is just @polybot/sdk plus a kleur-coloured front-end.

🔐 Security

• Wallet keys are encrypted before they leave your machine. Authenticated symmetric encryption with a per-user data key derived from a master secret.
• Plaintext keys live in memory only at sign time — wiped immediately after, never written to disk, never logged.
• Local cache stores only the address and a non-reversible 8-byte fingerprint in ~/.polybot/wallets.json.
• Pino log redaction strips privateKey, secret, passphrase automatically.
• Risk gates are non-bypassable — even by AI agents.
• Paper mode is the default for every CLI run and SDK instance.

See SECURITY.md for the threat model and disclosure policy.

📋 Requirements

• Node.js ≥ 20
• A Polygon wallet with USDC.e for live trading

That's it. No Docker, no Postgres, no Redis.

🤝 Contributing

PRs welcome — see CONTRIBUTING.md. The codebase is small on purpose: keep it that way.

📄 License

MIT — see LICENSE.