papertrade-alerts

Live app · Docs · Issues · Discussions · Papertrade · Toolkit

Unofficial, self-hostable alerts for Papertrade wallets. Know before the liquidation: get a Telegram, Discord or signed-webhook message when a position nears its bust price, opens, closes, is liquidated, when a session key is about to expire, or when staking rewards pile up.

Unofficial, not affiliated with Papertrade. High leverage can lose your whole margin. Alerts are best effort and can be late or missed.

Runs entirely on Cloudflare: one Worker (API + per-minute cron), D1 for state, and a static management UI served by the same Worker. Free-tier friendly for a handful of wallets (see Limits).

Screenshot: a dark dashboard with wallet cards (own and followed), channel cards with a "Send test" button and status chips, protocol alert switches, a recent-alerts feed with per-channel delivery badges, and a failed-deliveries view.

Quick start

npm install
cp .dev.vars.example .dev.vars
npm run dev:site          # builds the UI, applies local D1 migrations, serves on :8796
# trigger a poll by hand (the cron fires every minute on its own in production):
curl localhost:8796/cdn-cgi/handler/scheduled

Open http://localhost:8796, press "Create my subscription", save the token, add a wallet and a channel, then "Send test".

MCP server and AI connectors

The Worker hosts a stateless MCP server (Streamable HTTP) at /mcp: https://papertrade-alerts.ninabrekkerese.workers.dev/mcp. Ten tools: get_service_status, list_alert_types, preview_wallet_alerts (live read of any wallet, no account needed), validate_destination, create_subscription, add_destination, test_destination, create_alert_rule, list_alert_rules, delete_alert_rule. No tool signs, sends funds or places orders. Destinations are SSRF-guarded (https only, public hosts only), writes are rate limited per client and secrets are never logged.

claude mcp add --transport http papertrade-alerts https://papertrade-alerts.ninabrekkerese.workers.dev/mcp
codex mcp add papertrade-alerts --url https://papertrade-alerts.ninabrekkerese.workers.dev/mcp
gemini mcp add --transport http papertrade-alerts https://papertrade-alerts.ninabrekkerese.workers.dev/mcp

Cursor, VS Code, Windsurf, Zed, Cline, Goose, Continue, Claude Desktop, claude.ai, ChatGPT and the Claude and OpenAI APIs: see Connect your AI.

Discovery: /.well-known/mcp/server-card.json, /.well-known/agent-card.json, /.well-known/api-catalog, /openapi.json, /llms.txt, /llms-full.txt. Registry metadata: server.json.

Documentation

Markdown sources live in docs/ and are rendered by npm run build:docs (part of build:site) to /docs/ with search, a .md twin per page, llms.txt and llms-full.txt.

Embedding

/?embed=1 hides the marketing sections and shows only the product. The home page allows framing by https://papertrade-os.pages.dev and other *.pages.dev origins. "Open in Papertrade OS" links to https://papertrade-os.pages.dev/?open=alerts.

Features

• Wallet alerts: liquidation distance below X% of the bust price, position opened, closed (net PnL and PAPER minted from the settlement row), liquidated, balance change of at least $X, session key expiring within N days, pending staking rewards above $X.
• Protocol alerts: PAPER mint rate crossing a threshold, a market paused or close-only, a followed leaderboard wallet opening a position.
• Channels: Telegram (bot commands /start /watch /follow /unwatch /list /thresholds), Discord webhook, generic webhook signed with HMAC-SHA256. A channel with a missing secret is disabled with a visible reason.
• Engine: batched polling with bounded concurrency, shared 429 Retry-After gate, diff against stored state, edge-triggered thresholds with hysteresis, per-position dedupe keys, 60 alerts/hour per account and 20 sends/minute per channel, up to 6 delivery attempts with exponential backoff (30s doubling to 30 min), dead-letter view with one-click retry.
• All protocol math (bust price, mint rate, pending rewards) comes from papertrade-sdk.

Ownership: management tokens

There are no passwords and no wallet connection. POST /api/accounts returns a one-time token ptal_..., sent as Authorization: Bearer ptal_.... Only its SHA-256 is stored, so it cannot be recovered: save it in a password manager. Anyone with the token can manage that subscription, nobody can see another account. Telegram: messaging /start to the bot creates a chat-owned account and replies with a token once; /start <code> links a chat to a web account using a 15 minute code from the UI.

Why D1 and not KV

Alerts need uniqueness (dedupe keys), fan-out to several channels, ordered history for the UI and transactional state updates (alert + deliveries in one batch). KV is eventually consistent and has no queries or constraints. D1 gives all of that, and the working set is tiny.

Architecture

cron (* * * * *) -> runTick
  lease (120s) -> deliver due retries -> read trading state + prices
  -> protocol diff -> poll due wallets (SSE snapshot, concurrency 3, 50s budget)
  -> diffWallet (pure) -> alerts + deliveries (one D1 batch) -> deliver
UI/API (Hono): accounts, watches, channels, alerts, dead letters, Telegram webhook, read-only Papertrade proxy

Environment

Deploy

npx wrangler d1 create papertrade-alerts      # paste the database_id into wrangler.toml
npx wrangler secret put TELEGRAM_BOT_TOKEN    # optional
npx wrangler secret put TELEGRAM_WEBHOOK_SECRET
npm run deploy:site                           # builds UI, runs remote migrations, wrangler deploy
TELEGRAM_BOT_TOKEN=... TELEGRAM_WEBHOOK_SECRET=... npm run telegram:webhook -- https://<your-worker>.workers.dev

Limits

• The Papertrade live endpoint is rate limited per IP. The engine honors Retry-After, never counts a 429 as the wallet's fault and retries on the next tick.
• Cloudflare Workers Free allows 50 subrequests per invocation, enough for roughly a dozen wallets per minute. Use Workers Paid (1000 subrequests) for more and raise MAX_WALLETS_PER_TICK.
• Per account: 25 wallets, 6 channels.

Develop

npm run typecheck, npm test (diff engine runs on recorded real wallet snapshots in test/fixtures), npm run build:site.

The Papertrade toolkit

Nine open-source building blocks for Papertrade, the fully on-chain 1000x perps exchange on Hyperliquid HyperEVM. Use them together or on their own.

Contributing and support

• Found a bug or want a feature? Open an issue.
• Questions and show-and-tell: Discussions.
• Pull requests are welcome, see CONTRIBUTING.md. Security reports go through SECURITY.md.
• If this saved you time, a star helps other Papertrade traders and builders find it.

Built by three.ws.

Apache-2.0 licensed. Unofficial, not affiliated with Papertrade. High leverage can lose your whole margin.

Built by nirholas · @nichxbt · github.com/nirholas