Protocol Banks
Non-custodial Hyperliquid trading and crypto payments with a server-enforced spend cap.
Installation
Ajoutez ceci à la configuration MCP de votre client (Claude Desktop : claude_desktop_config.json ; Cursor : .cursor/mcp.json ; VS Code et les autres utilisent la même forme « mcpServers »).
claude mcp add --transport http protocol-banks 'https://protocolbanks.com/api/mcp'{
"mcpServers": {
"protocol-banks": {
"type": "http",
"url": "https://protocolbanks.com/api/mcp"
}
}
}Documentation
Tirée du README du projet sur GitHub, actualisée chaque semaine. Les liens ouvrent GitHub.
Sommaire
Protocol Bank — AI Automated Trading
Your AI trades. You keep control.
Overview
Protocol Bank is an AI automated trading product. Users connect a wallet (MetaMask), fund a trading budget on Hyperliquid, approve a trading-only agent wallet, and an AI agent trades perpetual markets around the clock — with strict risk controls, full transparency, and instant revocation. A paper-trading mode runs on real market data with simulated money, so anyone can watch the agent work risk-free.
The same execution layer is exposed as a programmatic API for AI agents: one credential, one policy the server enforces (operations, per-call cap, daily cap, coin allowlist), and an audit trail per operation. See docs/AGENT_API.md for the reference and docs/AGENT_CASES.md for four worked integrations.
Core safety properties:
- The AI can trade, never withdraw — the agent wallet holds trading-only permissions on Hyperliquid
- Worst case is written on the screen — the trading wallet is the maximum possible loss
- Guarded by construction — per-trade stop-loss, position caps, daily loss circuit breakers
- Revocable anytime — pause, emergency stop, or revoke the agent on Hyperliquid
The Product
| Area | Description |
|---|---|
AI Trading Cockpit (/trading) | Post-login landing: balances, equity curve, plain-language AI activity feed, open positions, pause/stop/reset controls |
| Paper Engine | Real Hyperliquid market data + simulated fills. Momentum (24h z-score) and funding-carry signals, 2.5% TP/SL, 15% position sizing, 5%/8% daily circuit breakers |
| Live Mode | Agent wallet approval flow (EIP-712 approveAgent), AES-256-GCM key custody, real IOC order execution signed by the agent key, uncertain-order safety halt, manual approval mode (opt-in), per-user isolation schema |
Wallet (/balances) | Multi-chain balances and activity (merged from the legacy dashboard) |
| Business (collapsed) | The legacy enterprise payment suite: batch payments, invoices, subscriptions, acquiring, vendors — available but no longer the hero |
Architecture
┌──────────────────────────────────────────────────────────────┐
│ Frontend — Next.js 15 (App Router, TypeScript, Tailwind) │
│ Landing → AI Trading cockpit → Wallet → Business (collapsed)│
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ API Routes (app/api) │
│ /api/trading/overview — tick-on-demand cockpit state │
│ /api/trading/actions — pause / resume / stop / reset │
│ /api/trading/live/* — agent wallet lifecycle (SIWE-auth) │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Trading engine (lib/trading) │
│ hyperliquid.ts — market data client (meta/ctxs/candles) │
│ strategies.ts — momentum + funding signals (pure) │
│ risk.ts — sizing, TP/SL, circuit breakers │
│ agent.ts — scan → signal → risk → execute → report │
│ exchange.ts — signed live orders (EIP-712) │
│ keys.ts — per-user agent key custody (AES-256-GCM) │
│ store.ts — paper state (file storage, tmp fallback) │
└──────────────────────────────────────────────────────────────┘
│
▼
Hyperliquid (public info API + signed exchange API)Quick Start
# Install
pnpm install
# Configure (see .env.example / ENV_SETUP.md)
cp .env.example .env.local
# Develop
pnpm dev # http://localhost:3000
# Run the trading agent headlessly (paper mode)
pnpm trading:agent
# MCP server — control the agent from Claude / any MCP host
pnpm mcp:stdio # stdio transport (see docs/MCP.md)
pnpm mcp:test # smoke-test tools/list + tools/callTesting & Quality Gates
| Command | What it runs |
|---|---|
pnpm test | Jest — 1035 unit/property tests |
pnpm test:ui | Playwright — browser E2E (own dev server on :3100) |
pnpm lint | ESLint 9 (0-error gate; legacy debt as warnings) |
npx tsc --noEmit | TypeScript typecheck |
pnpm build | Production build (Vercel deploy gate) |
go test ./... | Go microservices (in services/*) |
CI runs the full frontend suite (tsc + jest + lint) and Go tests on every push — see .github/workflows/ci.yml.
Documentation
| Document | Description |
|---|---|
| PRD v2 — AI Trading | Product spec: positioning, cockpit, wallet architecture, strategy & risk parameters |
| MCP Server | Control the trading agent from Claude Desktop / Claude Code / any MCP host |
| Usage Guide | In-product guide (getting started, cockpit, going live, FAQ) |
| Risk Disclosure | Read before live trading |
| Threat Model | Assets, trust boundaries and known limitations (uncertain orders, ledger drift, key custody) |
| Terms / Privacy | Legal |
| ENV_SETUP.md | Environment configuration |
| TESTING_GUIDE.md | Test infrastructure details |
| Agent API | Programmatic surface for agents: policy, endpoints, errors, billing |
| Agent API contract | OpenAPI 3.1 for the five agent endpoints — policy schema, error classes, real examples |
| Agent API cases | Four worked integrations with real requests and responses |
| Agent tools | One tool manifest for the Vercel AI SDK, LangChain, OpenAI and Anthropic |
| Framework starters | Runnable Vercel AI SDK, Mastra and elizaOS integrations |
| Partners | Partner integration guide (curl, SDK, sandbox, billing) |
Legacy payment-era docs remain in docs/ for the Business feature set.
Security Model
- SIWE + JWT authentication for wallet users (
lib/auth/siwe.ts,lib/middleware/api-auth.ts) - Non-custodial: user keys never leave their wallet; agent keys are trading-only and encrypted at rest
- Risk guardrails enforced before every order (lib/trading/risk.ts)
- Per-user isolation:
TradingAccount/TradeRecordmodels with wallet-address scoping - Rate limiting, CSRF, replay protection, security headers (middleware.ts)
License
GNU General Public License v3.0 only (GPL-3.0-only) — see LICENSE and ADDITIONAL_LEGAL_TERMS.md.
中文文档
项目简介
Protocol Bank 是一款 AI 自动交易产品。用户连接钱包（MetaMask），在 Hyperliquid 存入交易预算，批准一个仅有交易权限的 agent 钱包后，AI 代理全天候交易永续合约市场——配有严格风控、全程透明、随时可撤销。Paper 模式使用真实行情 + 模拟资金，任何人都可以零风险体验。
核心安全属性：
- AI 只能交易，永远无法提现——agent 钱包在 Hyperliquid 上仅有交易权限
- 最大亏损永远写在屏幕上——交易钱包余额即最大可亏损额
- 风控内建于每笔订单——止损、仓位上限、日内亏损熔断
- 随时可撤销——暂停、紧急停止、或在 Hyperliquid 上撤销 agent
核心功能
| 模块 | 说明 |
|---|---|
AI 交易驾驶舱 (/trading) | 登录后落地页：余额、净值曲线、自然语言 AI 活动流、持仓、暂停/停止控制 |
| Paper 引擎 | 真实 Hyperliquid 行情 + 模拟成交。动量（24h z-score）+ 资金费率信号，±2.5% 止盈止损，15% 仓位，5%/8% 日内熔断 |
| Live 模式 | Agent 钱包批准流（EIP-712 approveAgent）、AES-256-GCM 密钥托管、由 agent 密钥签名的真实 IOC 下单、不确定订单安全停机、人工审批模式（可选）、每用户隔离 schema |
钱包 (/balances) | 多链余额与流水（合并自旧 Dashboard） |
| Business（折叠区） | 企业支付套件：批量支付、发票、订阅、收单、联系人——保留但不再主推 |
快速开始
pnpm install
cp .env.example .env.local # 见 ENV_SETUP.md
pnpm dev # http://localhost:3000
pnpm trading:agent # 后台常驻运行交易 agent（paper 模式）
pnpm mcp:stdio # MCP server：在 Claude 里查询/控制 agent（见 docs/MCP.md）测试与质量门禁
| 命令 | 内容 |
|---|---|
pnpm test | Jest — 1035 项单元/属性测试 |
pnpm test:ui | Playwright 浏览器 E2E |
pnpm lint | ESLint 9（0 错误门禁） |
npx tsc --noEmit | 类型检查 |
pnpm build | 生产构建（Vercel 部署门禁） |
go test ./... | Go 微服务测试 |
文档
| 文档 | 说明 |
|---|---|
| PRD v2 — AI 交易 | 产品规格 |
| MCP Server | 在 Claude 等 MCP 客户端里查询/控制交易 agent |
| 使用指南 | 上手、驾驶舱、上线流程、FAQ |
| 风险披露 | 实盘前必读 |
| 条款 / 隐私 | 法律文档 |
⚠️ 风险提示：自动交易可能导致交易钱包全部损失。AI 是工具而非收益保证，历史表现不代表未来结果。Protocol Bank 不提供投资建议。
Questions fréquentes
Qu'est-ce que Protocol Banks ?
Non-custodial Hyperliquid trading and crypto payments with a server-enforced spend cap.
Comment installer Protocol Banks ?
Il fonctionne comme serveur distant. Dans Claude Code : claude mcp add --transport http protocol-banks 'https://protocolbanks.com/api/mcp'. Pour les autres clients, collez la configuration JSON de cette page dans leurs réglages MCP.
Faut-il une clé API pour Protocol Banks ?
Son entrée au registre n'indique aucune clé ni secret obligatoire. Certaines fonctions peuvent tout de même demander un compte auprès du service auquel il se connecte.
Qui maintient Protocol Banks ?
Il est publié par everest-an. AI.tn le référence sans le maintenir ni le recommander.
Issu du registre MCP officiel. Être listé n'est pas une recommandation : vérifiez le code et les permissions d'un serveur avant de lui donner accès à vos données.