HyperGrok
Grok Bot for Hyperliquid. Seven agents, one writer, your approval.
Works in Grok Bot · Claude Code · Cursor · Codex · Gemini CLI · Grok Build
HyperGrok is an open-source Hyperliquid trading desk for AI agents: seven role profiles and seventeen agent skills for research, risk, execution and review. It runs in Grok Bot and installs as a plugin in Claude Code, Cursor, Codex, Gemini CLI and Grok Build. It starts read-only on public market data; trading needs your own API wallet and a ticket you approve.
Try it now, no keys
git clone --depth 1 --branch v1.6.1 https://github.com/galleonlabs/hypergrok-trading-desk.git
cd hypergrok-trading-desk
python3 scripts/opening_bell.py --coin ETHA live ETH snapshot from Hyperliquid's public /info endpoint: price, funding, open interest, spread and depth. It needs no wallet, account or key, and runs on Python 3's standard library.
Start
The Desk Lead in Grok Bot opens with the same zero-key market snapshot, builds research, risk, execution and review as separate agents, then proves the floor is ready. Open Grok Bot and paste this to a Bot:
Set up the HyperGrok trading desk from https://github.com/galleonlabs/hypergrok-trading-desk/blob/v1.6.1/skills/hypergrok-bootstrap/SKILL.md. Follow the bootstrap skill, use https://github.com/galleonlabs/hypergrok-trading-desk/blob/v1.6.1/SETUP.md for the complete runbook, and finish with its evidence receipt.
Or add the public HyperGrok Desk Lead template, then send Start the desk. Its v1.6.1 bootstrap installs the complete seventeen-skill release and verifies native role and skill instructions. Publication evidence is recorded separately.
The desk starts in research mode. The first demo uses only Hyperliquid's public /info endpoint: no wallet, account read or order. Add a testnet API wallet when you want to practise with play money, and a mainnet one when you are ready.
Opening Bell
The first thing the Desk Lead shows is that snapshot: live market output, not a configuration form. It reports source and UTC time, mid/mark/oracle, 24-hour change and volume, hourly funding, open interest, spread and depth at 5/10/25 bps. Twenty book levels stop a few bps from the mid on a liquid perp, so it re-reads the book at a coarser nSigFigs page until each band is measured, names the page every figure came from, and still marks a band no page reaches as a floor rather than a total. scripts/desk_doctor.py then checks the release, team files, the reviewed skill bytes, desk folders and public connectivity. Both are read-only and standard-library Python.
For automated reads, inspect --schema without touching the network, then use --json. Success and errors have a versioned contract; a failed read remains unavailable, and incomplete depth and doctor warnings retain their meaning. Snapshots accept canonical mixed-case coins and explicit HIP-3 markets:
python3 scripts/opening_bell.py --schema python3 scripts/opening_bell.py --coin xyz:TSLA --json python3 scripts/desk_doctor.py --offline --json
--testnet explicitly selects testnet. A custom API origin is labelled custom. HIP-3 discovery stays read-only; execution remains opt-in under the desk's normal ticket rules.
History you can check
Before a backtest, collect the exact period into a research bundle:
python3 scripts/research_dataset.py --coin ETH --interval 4h \ --start 2026-09-01T00:00:00Z --end 2026-10-01T00:00:00Z \ --with-funding --output /workspace/trading-desk/data/eth-september --json python3 scripts/research_dataset.py --verify /workspace/trading-desk/data/eth-september --json
The bundle keeps requests, captured responses, observed CSV rows and a hashed manifest. Closed UTC windows, explicit missing ranges and bounded funding pagination distinguish complete, incomplete and unavailable history. Offline verification replays the saved responses; it checks consistency, not source authenticity or strategy quality. The tool needs no key and never fills a gap with synthetic data. See Research datasets for the supported intervals, market selection, exit codes and analyst handoff.
Meet the desk
They brief you on markets, size your trades, send what you approve and tell you honestly how it went. You bring the ideas. Let them cook.
| Bot | What they do for you |
|---|---|
| Desk Lead | Your main contact. Runs the floor, keeps every trade moving through the same clean process. |
| Market Analyst | Live Hyperliquid data on demand: price, depth, funding, open interest, candles. Timestamped and sourced. |
| Research Analyst | What is happening and what is scheduled: fundamentals, news, catalysts, onchain and social context. |
| Strategist | Turns your idea into explicit rules, backtests it honestly on Hyperliquid history, paper-trades it on testnet. |
| Risk Manager | Keeps your written limits, sizes every trade from your live account, watches the book, and can say no. |
| Execution Trader | The one Bot with the keys. Sends the ticket you approved, once, and reconciles it from the exchange record. |
| Trade Reviewer | Keeps the desk journal and grades every trade on process and outcome, separately. |
Six sit together on the Trading Floor group chat; the Trade Reviewer works by DM. Every trade follows the same path:
idea -> evidence -> risk sign-off -> your approval -> one send -> reconciliation -> review
A day on the desk
"Brief me on ETH." The Market Analyst pulls mid, mark, funding, open interest, 24h volume and depth at 5/10/25 bps from the exchange, and posts a brief with sources and UTC times.
"I want to long ETH at 3,000 with a stop at 2,900." The Desk Lead opens HG-20260816-01, the Risk Manager reads your account live and comes back with a ticket:
TICKET HG-20260816-01 | mainnet
market ETH-PERP side buy size 0.4827 ETH (~$1,448)
entry limit 3,000 Gtc stop sell 0.4827 @ 2,900 market (sent with the entry)
risk $51.00 = 0.5% of equity $10,200 (clearinghouseState 14:11 UTC) R = 100
sized on a stressed stop: 100 + 3.00 slippage + 2.65 fees = 105.65 per ETH
approve with: "approve HG-20260816-01"
You type approve HG-20260816-01. The Execution Trader sends entry and stop in one grouped order, reads the exchange response, confirms it on the book, and reports the order ids. When it closes, the Trade Reviewer tells you what it cost, whether the process was clean, and one thing worth keeping.
"Can we test whether funding extremes mean-revert?" The Strategist writes the rules with you, requests the agreed candle and funding history, and verifies its coverage before running the backtest. Missing history stays visible. Results include fees, funding assumptions, an out-of-sample split and the trade distribution. Like it? Paper-trade it on testnet through the same desk.
"Watch ETH and tell me if funding flips negative." A routine on the desk computer watches the WebSocket feed and pings you when it happens.
What the desk knows
Seventeen skills, in the portable SKILL.md format, shared by all your Bots.
Bootstrap - pinned release install, Opening Bell, team construction, desk doctor and a receipt that distinguishes what happened from what still needs a manual step.
Hyperliquid - setup and API wallets, market data, account state, orders (limit, IOC, take-profit and stop-loss with grouping, client order ids), positions and margin, WebSocket feeds, advanced actions (dead-man's switch, TWAP, spot), and a compact API reference. Copy-pasteable curl for reads; the official Python SDK and @nktkas/hyperliquid for anything that signs.
Desk - how the team works: operating model, the trade lifecycle and ticket, risk limits and sizing arithmetic, the execution protocol, monitoring and routines, post-trade review, incident playbooks, and the strategy lab.
Other agent setups
HyperGrok is for a coordinated Hyperliquid desk in Grok Bot. For a different setup, these Galleon projects can help:
- Boomkin sets up a native Hermes DeFi profile with modular skill packs and official tool connections.
- crypto-defi-skills lets you add individual workflows to an existing agent: lending, liquidity provision, routing, portfolio review and more.
Neither is required to use HyperGrok. Installing instructions does not connect a wallet or authorize a trade.
Built for real money
- You approve every trade, by ticket id, after seeing the exact order. The line you type is evidence; the gate that enforces it sits outside the chat, in Grok Bot's own Require Approval rule, because a Bot that can read an approval could also write one.
- A trade-only API wallet, provisioned through Grok Bot's secure secret store, is the only key the desk ever holds. It can trade; it cannot withdraw.
- Sized on a stressed stop. A triggered stop is a market order: it slips past the trigger and pays the taker fee. The desk sizes on what the stop will actually cost, not its trigger price, and charges the entry at the taker rate too, so your risk budget means what it says. See what a stop costs.
- Ceilings you cannot trade through. Your limits file may only tighten the desk's own caps, never loosen them.
- Testnet first. Every new kind of action is rehearsed with play money before it touches mainnet.
- One writer. Six Bots read; one Bot sends, once per approval, and reconciles by client order id.
- A reviewer who keeps you honest. Process and outcome graded separately, in a journal you can read.
Perpetual futures can liquidate an account. HyperGrok is documentation and instructions, not financial advice.
Also runs in Grok Build, Cursor, Claude Code, Codex and Gemini CLI
The plugin supplies seventeen skills and seven roles as subagents. Cursor and Claude Code load agents/, skills/ and rules/.
In Claude Code, install it from this repository:
/plugin marketplace add galleonlabs/hypergrok-trading-desk
/plugin install hypergrok@hypergrok
In Claude Code the plugin adds a hook that asks you to confirm any command that looks like a Hyperliquid exchange write, even in auto mode. It is a backstop: approval still happens by ticket id. Codex and Gemini CLI do not load it.
In Grok Build, install the reviewed release. The installation format was tested with Grok Build 1.0.30 for an earlier release; 1.6.1 has no native installation proof yet.
grok plugin install galleonlabs/hypergrok-trading-desk@v1.6.1 --trust
Grok Build reports the skills and agents directories; loading rules/ is not verified.
Alternatively, register this repository’s Grok marketplace and install by name:
grok plugin marketplace add galleonlabs/hypergrok-trading-desk grok plugin install hypergrok --trust
The marketplace index on main pins the same reviewed release.
In Cursor, open the repository and enable the plugin.
In Codex, add this repository's marketplace and install by name:
codex plugin marketplace add galleonlabs/hypergrok-trading-desk codex plugin add hypergrok@hypergrok
Codex reads .agents/plugins/marketplace.json, which pins the same reviewed release as the Grok index. It loads the seventeen skills but has no subagent component, so the roles run as labelled passes. Codex CLI 0.160.0 installed 1.6.1 through this index and listed all seventeen skills.
In Gemini CLI, install the extension:
gemini extensions install https://github.com/galleonlabs/hypergrok-trading-desk
Gemini CLI installs the latest GitHub release and loads the seventeen skills and GEMINI.md, which repeats the desk's approval rule. Its subagent schema does not accept the role files' frontmatter, so the roles run as labelled passes there too. gemini-extension.json follows the official extension format and first ships in 1.6.1; it has no native installation proof yet.
The same pack installs as a skill:
npm exec --package=skills@1.5.23 -- skills add galleonlabs/hypergrok-trading-desk
The complete resources also install from npm:
npm install --save-exact --ignore-scripts hypergrok-trading-desk@1.6.1 python3 node_modules/hypergrok-trading-desk/scripts/desk_doctor.py --offline
The package contains the instructions, role profiles, plugin manifests and read-only Python tools. It has no JavaScript entry point, runtime dependencies or install hooks; installation does not start a desk or connect a wallet.
Live listings: skills.sh · cursor.directory · botdirectory.ai
Either way, start with the desk-operating-model skill; where skills are slash commands, run /desk-operating-model.
Inside the repository
SETUP.md what your Grok Bot follows to build the desk
agents/ seven roles: Bot profile card + full system prompt
skills/ seventeen skills (bootstrap, hyperliquid-*, desk-*)
template/ exact public Grok Bot profile and skill hashes
scripts/ zero-key market, history and stop-cost reads, offline verification, release checks
docs/ how it works, FAQ, install pages, stop cost, provenance
assets/ the mascot (use it as your Bots' avatar) and the README illustration
| Doc | |
|---|---|
| How the desk works | roles, files, trust boundaries |
| FAQ | keys, approvals, testnet, customising the team |
| Research datasets | collect, verify and hand off historical evidence |
| Stop cost | what a triggered stop costs, from the live book |
| Skills index | every skill and who uses it |
| Grok Bot template | public profile, publish contract and clean-install evaluation |
| Provenance | sources and licences |
| Contributing · Security · Changelog |
License and credit
MIT licensed, with the copyright and permission notice retained when reusing copies or substantial portions. Created by Andrew Wilkinson and Galleon Labs.
See reuse and attribution for a ready-to-copy credit line. If HyperGrok Trading Desk helps your work, a star on the original repository is appreciated and entirely optional.
HyperGrok has no token and will not launch one. Read the FAQ.