Protocol Banks

Protocol Bank — AI 自动化交易

---

概览

Protocol Bank 是一款 AI 自动化交易产品。用户连接钱包（MetaMask），向 Hyperliquid 存入交易预算，批准一个仅用于交易的 Agent 钱包，随后 AI Agent 全天候交易永续市场，并通过严格的风险控制、全面的透明度和即时撤销功能保障安全。模拟交易模式使用真实市场数据和虚拟资金，让任何人都能无风险地观察 Agent 运作。

同一执行层也以面向 AI Agent 的编程 API 形式提供：一份凭证、一套由服务端强制执行的策略（操作、单次调用上限、每日上限、币种允许列表），以及逐项操作的审计记录。参考文档见 docs/AGENT_API.md，四个完整集成示例见 docs/AGENT_CASES.md。

核心安全特性：

• AI 可以交易，但绝不能提现 — Agent 钱包在 Hyperliquid 上仅拥有交易权限
• 最坏情况会显示在屏幕上 — 交易钱包中的资金就是可能发生的最大损失
• 从设计上确保安全 — 每笔交易都设有止损、持仓上限和每日亏损断路器
• 随时可撤销 — 可在 Hyperliquid 上暂停、紧急停止或撤销 Agent

产品

区域	描述
AI 交易控制台 (/trading)	登录后的首页：余额、权益曲线、通俗易懂的 AI 活动动态、未平仓位，以及暂停／停止／重置控制
模拟交易引擎	真实 Hyperliquid 市场数据 + 模拟成交。动量（24 小时 z-score）和资金费率套利信号、2.5% 止盈／止损、15% 仓位规模、5%／8% 每日断路器
实盘模式	Agent 钱包审批流程（EIP-712 approveAgent）、AES-256-GCM 密钥托管、由 Agent 密钥签名的真实 IOC 订单执行、不确定订单安全停机、手动审批模式（可选）、用户隔离架构
钱包 (/balances)	多链余额与活动记录（从旧版控制台合并而来）
业务（已折叠）	旧版企业支付套件：批量付款、发票、订阅、收单、供应商 — 仍可使用，但不再是核心功能

架构

┌──────────────────────────────────────────────────────────────┐
│ 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)

快速开始

# 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/call

测试与质量门禁

命令	执行内容
pnpm test	Jest — 1035 个单元／属性测试
pnpm test:ui	Playwright — 浏览器端到端测试（在 :3100 启动独立开发服务器）
pnpm lint	ESLint 9（错误门禁为 0；旧代码遗留问题作为警告处理）
npx tsc --noEmit	TypeScript 类型检查
pnpm build	生产构建（Vercel 部署门禁）
go test ./...	Go 微服务（位于 services/*）

每次推送时，CI 都会运行完整的前端测试套件（tsc + jest + lint）和 Go 测试 — 详见 .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 / TradeRecord models 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 不提供投资建议。