perpad MCP server
Commit Nov 13, 2026Enables AI agents to execute autonomous perpetual trading on Hyperliquid with deterministic risk enforcement and a tamper-evident journal.
Also known as nirholas/perpad
- Stars
- 4
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is perpad MCP?
perpad enables AI agents to execute autonomous perpetual trading on Hyperliquid with deterministic risk enforcement and a tamper-evident journal.
Summary generated from the project's README
About perpad MCP server
Executing autonomous perpetual trades on Hyperliquid with strict safety guardrails is what perpad enables for developers building AI trading agents. Unlike standard implementations that rely solely on model instructions, this system uses a deterministic risk engine written in pure code to enforce limits that an LLM cannot override. It manages isolated-margin perps for assets like BTC and ETH while ensuring every action follows predefined constraints.
Users can deploy this in paper mode using simulated fills and real prices, or go live by providing a Hyperliquid API wallet key and account address. The setup requires an Anthropic API key for the agentic logic. To ensure accountability, the server maintains a SHA-256 hash-chained journal that records every thought, action, and refusal in a JSONL format. This allows for easy verification of the agent's decision-making history through the perpad verify command.
What you can do with it
- 1Simulate trading strategies safelyTest autonomous trading logic using real market prices and simulated fees without risking actual capital.
- 2Audit agent decision historyVerify the integrity of an agent's trading logs to ensure no entries have been tampered with.
- 3Monitor market data via MCPUse the MCP server to allow an AI client to inspect available markets and check current risk status.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
ANTHROPIC_API_KEY
| Name | Description | |
|---|---|---|
| ANTHROPIC_API_KEY | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablenirholas/perpad is public and reachablegithub.com/nirholas/perpad ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/nirholas/perpad ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubperpad
Autonomous perp-trading agents on Hyperliquid, with limits the model cannot override.
Docs · Quickstart · Risk engine · Roadmap
An LLM agent reads live BTC and ETH prices from Hyperliquid, checks its account, then opens or closes isolated-margin perps. Every order passes a deterministic risk engine. Every thought, action and refusal is written to a hash-chained journal anyone can verify.
┌────────────┐ 5 tools ┌──────────────┐ clamp / deny ┌────────────┐
tick → │ Claude │ ─────────▶ │ risk engine │ ─────────────▶ │ venue │ → Hyperliquid
│ (agent) │ ◀───────── │ (pure code) │ │ live/paper │
└─────┬──────┘ verdicts └──────────────┘ └────────────┘
└──────────── every step ──▶ hash-chained journal (JSONL)
Why
Most trading-agent demos give a model an exchange key and hope. perpad inverts that. The model has five tools and no way to withdraw, transfer, change limits or use cross margin. The only path to an order runs through code that reads live exchange limits. If the model asks for 100x on a 40x market it gets 40x or a refusal, and the refusal is journaled.
Quickstart (paper mode, no exchange key)
git clone https://github.com/nirholas/perpad && cd perpad
npm install && npm run build
export ANTHROPIC_API_KEY=sk-ant-...
node dist/cli.js run examples/btc-eth.json --once
node dist/cli.js verify journal/tidewatcher.jsonl
Paper mode uses real Hyperliquid prices with simulated fills, the 0.045% taker fee and isolated liquidation. Going live needs HL_PRIVATE_KEY (a Hyperliquid API wallet, which can trade but not withdraw), HL_ACCOUNT_ADDRESS, and both --live --i-understand-real-funds. Try "testnet": true first.
Features
| Hard limits | Allowed markets, max leverage clamped to the live exchange cap (BTC 40x, ETH 25x today), margin per trade, open positions, daily-loss kill switch |
| Journal | SHA-256 chained JSONL. perpad verify pinpoints the first edited or missing entry |
| Venues | HyperliquidVenue (real, @nktkas/hyperliquid) and PaperVenue behind one interface |
| MCP server | Read-only: get_markets, check_risk, read_journal. Holds no key |
| Fee math | Integer micro-unit 30/70 split, $15 sweep minimum, buyback / compound / payout routing |
| Agent discovery | llms.txt, llms-full.txt, A2A agent card, MCP metadata, AGENTS.md |
Library
import { Agent, Journal, PaperVenue, HyperliquidPrices } from "perpad";
const venue = new PaperVenue(new HyperliquidPrices(), 1000);
await new Agent(config, venue, new Journal("journal/a.jsonl")).tick();
import { evaluate } from "perpad";
evaluate(
{ coin: "BTC", side: "long", leverage: 100, marginUsd: 900 },
{ openCoins: [], withdrawableUsd: 1000, dailyPnlUsd: 0, exchangeMaxLeverage: { BTC: 40 } },
{ markets: ["BTC"], maxLeverage: 50, marginPerTradeUsd: 100, maxOpenPositions: 1 },
); // { allowed: true, adjusted: { leverage: 40, marginUsd: 100 } }
MCP
{ "mcpServers": { "perpad": { "command": "npx", "args": ["-y", "github:nirholas/perpad", "mcp", "journal/agent.jsonl"] } } }
Status and roadmap
v0.1 ships the trading core, journal, paper and live venues, MCP server and fee math, covered by 21 tests including a live Hyperliquid read. The Solana leg (claim pump.fun creator fees, swap, bridge, deposit to Hyperliquid), coin launch flow, buybacks and journal anchoring are on the roadmap. They are not shipped and nothing here pretends otherwise.
Security and risk
Leveraged perps can lose all margin quickly. This is software, not financial advice, and makes no profit claims. Read the security model and SECURITY.md. Independent project, not affiliated with Hyperliquid, pump.fun or Anthropic.
Contributing
PRs welcome. See CONTRIBUTING.md. Questions and ideas go to Discussions.
Development
npm test # 21 tests, includes a live read-only Hyperliquid call
npm run typecheck
npm run site:build # regenerates docs/ (GitHub Pages)
MIT © nirholas
Support the project
If perpad saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.
Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit
Built for AI agents too
Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/perpad and it has the context it needs.
More from the same author
- All repositories by nirholas: the full catalog, grouped by topic
- three.ws: the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments
- Questions or ideas: open an issue or start a discussion
Contributors
Star history
perpad MCP questions
Can the AI agent override risk limits?
No, the model operates within hard limits enforced by a deterministic risk engine that the model cannot bypass.
How can I test the trading agent without using real funds?
You can use paper mode, which uses real Hyperliquid prices with simulated fills, taker fees, and isolated liquidation.
What is the purpose of the journal?
The journal is a SHA-256 hash-chained JSONL file that records every thought, action, and refusal for verification.
Is the MCP server capable of executing trades?
The MCP server is read-only and holds no keys, providing tools to get markets, check risk, and read the journal.