Local CLI
Run Papertrade AI on your own machine with npx. Browser wallet login, headless session keys for bots, read-only mode and every environment variable.
papertrade-ai on npm is a stdio MCP server plus a small CLI. Use it when you want the session key on your own disk instead of the hosted server, or for bots and CI.
npx -y papertrade-ai --help
Requires Node.js 20.10 or newer.
Commands#
| Command | What it does |
|---|---|
papertrade-ai | Start the stdio MCP server (what your MCP client runs). |
papertrade-ai login | Open a local browser page, connect your wallet, pick read-only or trading with guardrails. |
papertrade-ai login --key | Headless: register a trading session key using PAPERTRADE_PRIVATE_KEY. |
papertrade-ai status | Show the connected wallet, mode, session expiry and guardrails. |
papertrade-ai logout | Delete the saved credentials. |
Browser login#
npx -y papertrade-ai login
The CLI starts a one-time page on 127.0.0.1 with a random port and opens it. You connect your wallet (any EIP-6963 browser wallet), choose a mode, set guardrails and sign. Credentials are saved to ~/.config/papertrade-ai/credentials.json with mode 0600. The page shuts down after 15 minutes.
Headless#
For bots and servers, set the wallet key only for the login step. The key signs the session key registration and is never stored:
PAPERTRADE_PRIVATE_KEY=0x... PAPERTRADE_MAX_LEVERAGE=200 npx -y papertrade-ai login --key
If PAPERTRADE_PRIVATE_KEY is set when the server starts, it reuses a live saved session or registers a new one automatically.
Read only, no login#
PAPERTRADE_WALLET=0xYourWallet npx -y papertrade-ai
Without any wallet, every public market and analytics tool still works.
Environment variables#
| Variable | Default | Meaning |
|---|---|---|
PAPERTRADE_WALLET | Read-only wallet address | |
PAPERTRADE_PRIVATE_KEY | Wallet key used only to sign a session key registration | |
PAPERTRADE_MAX_MARGIN_USD | 50 | Guardrail: max margin per trade |
PAPERTRADE_MAX_LEVERAGE | 500 | Guardrail: max leverage |
PAPERTRADE_MAX_DAILY_NOTIONAL_USD | 250000 | Guardrail: max position size opened per rolling 24h |
PAPERTRADE_MAX_OPEN_POSITIONS | 5 | Guardrail: max open positions |
PAPERTRADE_MARKETS | BTC,ETH | Guardrail: allowed markets |
PAPERTRADE_REQUIRE_CONFIRMATION | true | Guardrail: the model must confirm every trade with you |
PAPERTRADE_CONFIG_DIR | ~/.config/papertrade-ai | Where credentials are stored (respects XDG_CONFIG_HOME) |
Guardrails from environment variables apply to headless sessions. Browser login uses the values you set on the page.
Session expiry#
Session keys last 30 days. When one expires the server falls back to read-only and prints a note to stderr; run login again.