LiqGuard

LiqGuard warns perpetual-futures traders before liquidation. Meta Muse explains the risk and starts a PayPal checkout; a $2.99 Rescue Pass unlocks 24-hour Rescue Mode.

Comment

Inspiration

Perpetual-futures traders get liquidated in their sleep. The exchange app shows a liquidation price, but it does not tell you how close each position really is once cross-margin wallet effects and funding are counted, which of several positions to save first, or what saving it actually costs.

The alert that matters often arrives at 3 a.m. as a margin-ratio push notification. By the time the trader has done the maths, the position is gone. We wanted a bot that does that maths in advance, says what to do in plain language, and β€” when the trader needs a short burst of help β€” lets an AI agent start a real PayPal checkout, with the user still approving the payment.

PayPal is the rail. It is never used to fund a trading account or buy crypto; it only pays for LiqGuard's own subscription or pass.

What it does

LiqGuard is a Telegram bot (@futureswatchbot) and a live web dashboard (https://152-42-176-155.sslip.io) that watches Binance USDβ“ˆ-M and Hyperliquid perpetual futures. It binds only a read-only Binance API key or a Hyperliquid wallet address. It refuses seed phrases and other secret material it should not have.

It computes liquidation distance, stop-loss gaps, funding drift, and a rescue plan (add margin, reduce, or hedge, with fees and 24-hour funding). Meta Muse writes the explanation and the "handle this first" line, tagged so the numbers from code and the words from Muse stay distinct. Alerts escalate through warning, critical, and emergency tiers, with I'm awake and Snooze controls.

Everything is one tap from an inline-button menu, in English (default) or Traditional Chinese. A built-in demo mode (/demo, then 🎬 Liquidation sim) drives the whole product with simulated positions, so judges do not need an exchange account.

PayPal (sandbox) is how paid access is granted:

  • Free: 5 Muse requests per Taipei day (resets 00:00 Taipei), 1 bound account, 30-second scans, and a rescue-calculator preview.
  • Rescue Pass, $2.99 one-time (PayPal Orders): unlocks 24-hour Rescue Mode β€” unlimited Muse, 10-second scans, and the full rescue calculator. Buying again extends Rescue Mode by another 24 hours. The bot confirms Rescue Mode active until (Taipei).
  • Pro, $9.99 per month (PayPal Subscriptions): unlimited Muse, up to 5 bound accounts, 10-second scans, and the full rescue calculator. Pro users do not need a Rescue Pass.

Typing a request such as "get me a Rescue Pass" or "upgrade to Pro", or tapping πŸ€– Muse checkout on a liquidation alert, makes Meta Muse (muse-spark-1.3) pick a PayPal Agent Toolkit tool (create_order for Rescue Pass, or create_subscription for Pro). The bot shows "Muse chose this PayPal tool." A rules-based fallback is used only if Muse is unavailable. The model never chooses the price; the server fills in the fixed sandbox amount. Nothing is captured in the bot. The user approves the official PayPal checkout. A signature-verified PAYMENT.CAPTURE.COMPLETED webhook, or the PayPal return URL, unlocks the entitlement. Telegram updates immediately. If checkout was started while signed in, the return lands on the dashboard with a "Payment received β€” Rescue Mode is on until …" banner.

The dashboard uses AG Grid (alpine-dark) for positions, alert history, and billing, with a liquidation-distance color scale, a summary bar, a chart against warning / critical / emergency bands, a natural-language filter (for example "positions within 5% of liquidation"), and an audit log of every Muse PayPal tool call (agent_actions: tool, source, product).

How we built it

  • PayPal Orders v2 β€” one-time LiqGuard Rescue Pass at a fixed $2.99. Used for Rescue Mode.
  • PayPal Subscriptions β€” sandbox plan for LiqGuard Pro at $9.99 per month (PAYPAL_PLAN_ID).
  • PayPal Webhooks β€” PAYMENT.CAPTURE.COMPLETED grants Rescue Mode; BILLING.SUBSCRIPTION.ACTIVATED, CANCELLED, SUSPENDED, and PAYMENT.FAILED drive Pro status. Events are signature-verified against PAYPAL_WEBHOOK_ID and stored by event_id for idempotency. The PayPal return URL can also activate the entitlement if the webhook has not arrived yet. If the webhook ID is missing, POST /webhooks/paypal rejects with 503; verification is never skipped.
  • PayPal Agent Toolkit β€” Muse is given a tight tool surface aligned with the toolkit: create_order and create_subscription only. Execution always goes through our sandbox REST client. The host, not the model, fills amount, currency, and plan ID. Tool calls are logged to agent_actions.
  • Meta Muse (muse-spark-1.3, OpenAI-compatible API at api.meta.ai) β€” writes recommendations and chooses which PayPal tool to call. Liquidation prices, distances, rescue costs, and stop gaps stay in deterministic Python (liqguard/risk/).
  • AG Grid Community (MIT, alpine-dark) β€” live position, alert, and billing grids, plus the natural-language filter and the Muse PayPal action log. AG Charts Community (with a Chart.js fallback) draws distance against the risk bands.
  • aiogram 3 β€” Telegram bot, every feature reachable from an inline keyboard.
  • FastAPI + WebSockets β€” dashboard at the hosted URL, public /api/demo snapshot, and signed-in /api/me after /dashboard.
  • Binance USDβ“ˆ-M (read-only API key) and Hyperliquid (wallet address only).
  • Python 3.11, SQLite, Caddy in front of the live instance. MIT licensed.

Challenges we ran into

The hard part was not "add a PayPal button." It was making the payment agentic without being reckless. Muse may start a checkout, but it must never pick a price, never send funds to a trading account, and never buy crypto. That meant a deliberately small tool surface and host-owned amounts. When Muse is available, judges should see "Muse chose this PayPal tool." β€” not a silent, rules-only button.

Webhook security was the second constraint. Skipping signature verification "just for the demo" would have been the easy path and the wrong one. If PAYPAL_WEBHOOK_ID is unset, LiqGuard refuses the event. The return URL is a second, idempotent path so a completed payment still unlocks access if the webhook is delayed.

The third challenge was making paid tiers visible. A Rescue Pass that only incremented an unused counter would not survive a judge asking "what did I just pay for?" A captured order now unlocks a time-boxed Rescue Mode, with the expiry shown as a date and time in Taipei, and Muse immediately works again. Buying another pass extends that window.

Keeping English and Traditional Chinese complete β€” including billing and checkout copy β€” and keeping risk maths out of the model, were constant discipline rather than one-off bugs.

Accomplishments that we're proud of

  • A working sandbox path from Muse tool call β†’ PayPal order β†’ buyer or guest approval β†’ signed webhook or return URL β†’ Rescue Mode on, in the same product traders already use for alerts. On the live demo, a $2.99 sandbox guest checkout activated Rescue Mode, and Telegram confirmed the expiry in Taipei time.
  • A clear split: code computes risk, Muse explains it and starts checkout, PayPal takes the payment.
  • AG Grid that is part of the product, not a decorative table: color scale, risk-band chart, natural-language filter, and a real audit log of agent payments.
  • A public, bilingual demo that runs without an exchange account, so judges can try it in minutes.
  • Entitlements a judge can actually feel: 5 Muse requests a Taipei day on the free plan, then a $2.99 Rescue Pass that lifts the cap, speeds scans to 10 seconds, and unlocks the full rescue calculator for 24 hours.

What we learned

Agentic commerce only feels safe when the model's authority is narrow and the payment network stays in charge of capture. Fixed prices and a user-facing PayPal approval are not limitations; they are the product.

Webhook-first activation is more trustworthy than having the bot poll for payment, and the return URL is a useful backup when both paths are idempotent. The confirmation has to show what unlocked and until when, or the purchase feels like a no-op.

We also learned that a hackathon payment feature has to change the user's next action. If Muse still refuses the sixth question after a successful capture, the story falls apart β€” in the video and in real use.

What's next

  • Keep the hosted demo up through the judging period (1–15 Dec 2026, Pacific time).
  • More venues on the same read-only model (OKX and Bybit are on the public roadmap), plus rolling correlations from market data instead of fixed factors.
  • Portfolio-margin / multi-asset handling, still advisory-first.
  • Rules-based automation only later, opt-in and testnet-first. Protective actions stay off live trading unless the user confirms them on testnet.
  • Live (non-sandbox) PayPal only if and when the product is ready for real charges; this submission is sandbox-only.

How PayPal + AI is central

LiqGuard is not a trading bot with a PayPal button bolted on. Muse is the payment agent, and PayPal is the payment rail. When a free user hits the Muse daily limit β€” often in the same moment a position is close to liquidation β€” or types a request such as "get me a Rescue Pass," Muse can call create_order or create_subscription from a PayPal Agent Toolkit-aligned tool list. The server fills the fixed sandbox price ($2.99 Rescue Pass or $9.99/month Pro). The user approves the official PayPal checkout. A verified webhook or the return URL is what actually unlocks the AI: 24-hour Rescue Mode, or a Pro subscription. PayPal never funds a trading account and never buys crypto. That loop β€” AI starts the checkout, PayPal completes it, AI capacity is the thing purchased β€” is the core of the product and of this entry.

AI tools used

  • Meta Muse (muse-spark-1.3, OpenAI-compatible API at https://api.meta.ai/v1). Muse writes every recommendation and Ask Muse answer in English or Traditional Chinese, and it chooses which PayPal Agent Toolkit tool to call (create_order or create_subscription). Risk numbers are never left to the model: liquidation prices, distances, rescue costs, and stop gaps are computed in deterministic Python (liqguard/risk/). A rules-based fallback is used only if Muse is unavailable.
  • PayPal Agent Toolkit (aligned tool surface). Muse may start checkout; the host fills the fixed amount, currency, and plan ID, and PayPal remains the system of record for approval and capture.

Testing instructions for judges

Fastest path (no account required for the dashboard):

  1. Open the hosted demo: https://152-42-176-155.sslip.io. The public book is the built-in simulation (/api/demo); no login is required.
  2. In the Positions grid, confirm the liquidation-distance color scale and the summary bar.
  3. In the filter box, type within 5% of liquidation (or positions within 5% of liquidation) and confirm the grid narrows.
  4. Toggle EN / δΈ­ζ–‡. Optionally open the Distance to liquidation chart and the alert list.

Telegram demo (recommended, still no exchange account):

  1. Open @futureswatchbot on Telegram and send /start (or /demo).
  2. Use the English UI (or switch to 繁體中文). Tap 🎬 Demo, then 🎬 Liquidation sim. Do not bind a real exchange account.
  3. Watch alerts escalate. Buttons on an alert include πŸš‘ Handle this first, βœ… I'm awake, and 😴 Snooze 30 min.
  4. On a free-tier user, Ask Muse is capped at 5 requests per Taipei day (reset 00:00 Taipei); the sixth is an upsell.

PayPal sandbox (Rescue Pass / Pro):

  1. Pay in the PayPal sandbox only β€” not with a live card and not with live PayPal. Use a PayPal sandbox personal (buyer) account, or pay as a guest with a PayPal sandbox test card from PayPal's developer credit card generator.
  2. In the bot, type "get me a Rescue Pass" (clearest path) or, on a liquidation alert, tap πŸ€– Muse checkout. The bot should show "Muse chose this PayPal tool." Then buy the $2.99 Rescue Pass. For the $9.99/month subscription, type "upgrade to Pro", or use πŸ’Ž Pro / the dashboard Billing page (sign in with /dashboard from Telegram first).
  3. Approve the PayPal checkout. Nothing should be captured inside Telegram.
  4. After capture, Telegram should confirm Rescue Mode active until (Taipei) (Rescue Pass) or that Pro is active. If you started checkout while signed in on the web, the return lands on the dashboard with a "Payment received β€” Rescue Mode is on until …" banner. Ask Muse again; it should work. The signed-in dashboard billing panel and the Muse PayPal actions grid should show the tool call (create_order or create_subscription).
  5. If you self-host, follow the public README. Set PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET, PAYPAL_WEBHOOK_ID, PAYPAL_ENV=sandbox, and PAYPAL_PLAN_ID, and point a webhook at https://<your-domain>/webhooks/paypal. If PAYPAL_WEBHOOK_ID is missing, webhook posts are rejected.

Please do not paste production API keys, seed phrases, or live PayPal credentials. The product is advisory; it is not financial advice, and it does not use PayPal to fund trading or buy crypto.

Built With

Share this project:

Updates

Submission history