Quickstart

From a fresh clone of the open-source SDK to a verified receipt. Everything runs offline on recorded public data, and nothing asks for an API key or exchange keys.

Node 22.6 or newer is requiredCheck with node -v. On Node 20 or older, or Node 22.0–22.5, the examples stop with node: bad option: --experimental-strip-types; upgrade Node to fix it. On Node 22 a harmless ExperimentalWarning: Type Stripping line is printed.

1 · Install the MCP server

git clone https://github.com/PERPBRAIN/perpbrain-sdk.git
cd perpbrain-sdk/ts/mcp-server && npm ci
cd ../..
node bin/perpbrain-mcp.mjs

The launcher starts the stdio MCP server. To smoke-test it, pipe an initialize request followed by tools/list into it; it lists the 12 tools. Live reads use the public Hyperliquid /info endpoint, mainnet by default. Set PERPBRAIN_HL_NETWORK=testnet for testnet.

The same server from the repository root:

node bin/perpbrain-sdk.mjs mcp

2 · Check a receipt

node --experimental-strip-types examples/verify-receipt.ts fixtures/receipts/good
# {"dir":"fixtures/receipts/good","status":"VERIFIED","mismatches":[]}

VERIFIED means every hash re-derived from the inputs matches. Try a tampered fixture to see a precise mismatch and exit code 1:

node --experimental-strip-types examples/verify-receipt.ts fixtures/receipts/tampered-result
# "status":"MISMATCH","mismatches":["result_sha256 mismatch","result.fills[0].price mismatch"]

3 · Simulate under your limits

node --experimental-strip-types examples/guarded-simulate.ts

It simulates one decision under the Standard preset, then shows a looser 9x leverage blocked before a fill is recorded. Output is labelled SIMULATED. See owner limits.

4 · Drive the MCP handler

node --experimental-strip-types examples/mcp-fixtures.ts

It calls the read and simulation tools on recorded public data. submit_order is refused.

Work on the SDK itself

(cd sdk && npm ci && npm run build)

@perpbrain/sdk is 0.1.0-rc1 and not on npm yet. npm run build writes ESM and CommonJS builds to sdk/dist.

Read thisA simulation is a model, not a forecast. It is not advice and places no order. Limits you set; losses are still possible.