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.