reins

# Reins

**Let an AI agent trade without giving it the power to lose everything.**

```bash
npx @r2rlabs/reins init      # adds a paper-trading Reins server to .mcp.json
```

See it at work: [an AI agent trading Hyperliquid on paper, run 2](https://gist.github.com/R2Rlabs/246a5009684787a586ddee1d2615eb14).

The source is on GitHub: [R2Rlabs/reins](https://github.com/R2Rlabs/reins). Every limit in this README is a
function you can read.

### What Reins is

- **Limits the agent can't argue with.** Every order passes checks that live
  outside the model: position size, leverage, daily loss, which markets it may
  trade, and a stop-loss on every position. No prompt, clever reasoning or
  mistake gets around them.
- **A record you can check.** Every decision is logged with the reason the agent
  gave — including the orders it was refused, the times it chose to wait, and
  what the exchange did without it. You can compare what the agent *said* with
  what actually *happened*.
- **Somewhere to rehearse.** Paper trading on live Hyperliquid prices with
  realistic fills and fees, using the same tools and limits as live trading.
- **Non-custodial.** Your money stays in your own Hyperliquid account. Reins
  trades through an API wallet, which can place orders but cannot withdraw.
- **Paid for openly.** A small builder fee (2 bp) on live orders, shown up front.

### What Reins is not

- **Not a trading bot or a strategy.** Reins doesn't decide what to trade and
  won't make an agent profitable. The demo agent is a test drive, not the product.
- **Not an exchange, broker or custodian.** It holds no funds and matches no
  orders; Hyperliquid does that.
- **Not a promise against losses.** Limits cap how much can go wrong. They don't
  make bad trades good, and stops can slip in fast markets.
- **Not financial advice.**
- **Not something you have to take on trust.** Not the agent's word, and not
  ours: every action is on the record.

### Principles

1. Limits live outside the model.
2. The record outranks the reasoning.
3. Paper before real money.
4. Your keys, your funds.

## Why this exists

Several open-source Hyperliquid MCP servers already exist. They are thin API
wrappers: you hand them a private key and hope the model behaves. The gap is
everything around that — the limits, the sandbox, the audit trail. That is what
this repo is.

## Status

Early, but real. 391 tests, no network calls in any of them.

| Module | What it does |
|---|---|
| `src/risk.ts` | The risk engine — position cap, risk per trade, leverage cap, daily loss halt, allowlist, rate limit |
| `src/client.ts` | Hyperliquid REST client — orders, cancels, book, candles, fills, account state, builder code |
| `src/mcp-server.ts` | The agent-facing tools, each risk-checked and logged before anything is sent |
| `src/paper.ts` | Paper trading — live prices, simulated fills. See below |
| `src/paper-store.ts` | Persists a paper run across restarts |
| `src/trading-client.ts` | The interface live and paper both satisfy |
| `src/decision-log.ts` | Append-only record of every attempt and its stated reason |
| `src/decision-log-file.ts` | JSON Lines log on disk |
| `src/bin/cli.ts` | The `reins` command: `serve` (default), `init`, `approve-builder`, `live-check`, `http` and `stats` |
| `src/bin/serve.ts` | stdio entry point |
| `src/bin/http.ts` | `reins http` — the HTTP server: token, binding, JSON |
| `src/http-api.ts` | The same nine tools as HTTP routes, for bots that do not speak MCP |
| `src/runtime.ts` | The limits, client, log and banner both front doors share |
| `src/init.ts` | `reins init` — writes a paper-mode server entry into `.mcp.json` |
| `src/builder-fee.ts` | Reins' builder fee, and the approval live trading needs before it starts |
| `src/approve-builder.ts` | `reins approve-builder` — the user approves the builder fee in their own wallet |
| `src/live-check.ts` | `reins live-check` — proves the live exchange accepts what Reins sends |
| `src/platform-stats.ts` | `reins stats` — accounts, trades, volume and fees through Reins' builder code |
| `src/lz4.ts` | Reads Hyperliquid's LZ4-compressed data files, without a dependency |
| `src/builder-approval.ts` | The ApproveBuilderFee action: EIP-712 typed data, signature checks |
| `src/format.ts` | Price and size formatting to Hyperliquid's tick and lot rules |
| `src/signing.ts` | L1 action signing, verified against the Python SDK's vectors |
| `src/private-key-signer.ts` | A Signer backed by a private key |
| `src/signer.ts` | The Signer interface plus a stub. See "On signing" below |
| `src/mock-transport.ts` | In-memory API stand-in, so agents can be tested without a network |
| `examples/demo-agent/` | Claude trading on paper through Reins, producing a publishable decision log |

All of it works end to end. Going live is now a matter of funding an account and
setting `REINS_MODE=live` with a key.

### Going live

```bash
REINS_MODE=live
REINS_NETWORK=testnet          # mainnet spends real money
REINS_ACCOUNT_ADDRESS=0x...    # your Hyperliquid account
REINS_PRIVATE_KEY=0x...        # an API wallet's key, not your account's; omit to stay read-only
```

On mainnet, approve Reins' 2 bp builder fee once, from the account's own
wallet, before the first live session: `npx @r2rlabs/reins approve-builder`.
Until the account has, live mode refuses to start and says so.

**Use an API wallet, not your account's own key.** Hyperliquid lets an account
approve API wallets that can trade for it but cannot withdraw from it — create
one on Hyperliquid's API page, signing the approval with your main wallet. Put
its key in `REINS_PRIVATE_KEY` and your account's address in
`REINS_ACCOUNT_ADDRESS`: orders are signed by the API wallet, while positions,
fills and stops are read from the account, because under the API wallet's own
address the account looks empty. The startup banner names both. Hyperliquid
prunes API wallets that expire or are replaced; make a fresh one rather than
reusing an old address.

Every account mode works. Hyperliquid starts new accounts in **Unified**,
where the USDC sits in the spot balance and the perps account reads $0; Reins
asks the account which mode it is in and, for Unified and Portfolio margin,
takes equity from the USDC balance plus the positions' unrealized PnL. Manual
accounts are read from perps as before. (A *builder* address is different: it
must be in Manual — `standard` — to earn fees.)

Defaults are deliberately safe: `REINS_MODE` is `paper` and `REINS_NETWORK` is
`testnet`, so trading real funds takes two explicit changes rather than one
forgotten variable. Live mode without a key stays read-only instead of failing
at the first order, and mainnet prints a loud banner on startup.

The private key is only read in live mode — paper never signs anything, so it is
never handed the means to.

## See it run

```bash
npm run build
npm run demo -- --scripted      # free: no API key, live prices, paper fills
```

With an Anthropic API key, `npm run demo` runs Claude as the agent under a hard
spending cap. See [`examples/demo-agent`](examples/demo-agent/) for cost, limits and how
to publish the result honestly.

## The decision log

Every attempted action is appended to a log with the reason the agent gave for
it — **including the ones the risk limits refused.** That is the point. "The
agent tried to open six times its position cap at 3am, and here is what it said
it was doing" is the most useful thing this system can tell you, and it only
exists if refusals are written down.

`place_order`, `close_position` and `set_stop_loss` take a **required** `reason`. An optional
field gets omitted; a required one gets answered.

Records are JSON Lines — one self-contained object per line, appended, never
rewritten. Appends stay cheap as the file grows, a truncated write damages one
line instead of the file, and you can query it with ordinary tools:

```bash
jq -r 'select(.risk.allowed == false) | [.time, .risk.code, .reason] | @tsv' decisions.jsonl
```

Each record holds the stated reason, the request, the account context at the
time, the risk verdict, and the outcome. Set `REINS_LOG_FILE` to persist it;
without it the log lives in memory and dies with the process.

The exchange also acts on its own: a stop-loss fires, a resting order fills
hours after it was placed. Before every tool call Reins compares the account's
fills with the log and appends each one it has not seen as an `exchange_fill`
record, whose reason starts "Not an agent decision:" and says whether it was a
stop, a resting order, or a fill Reins did not place. Without them the trade
that mattered most, the stop that closed it, would be missing from the record.
The agent reads them back through `get_recent_decisions` like anything else.

### Two things to be clear about

**`reason` is testimony, not ground truth.** It is the model's own account of
why it acted, captured because reasoning that is not asked for cannot be
recovered later. A model can rationalise after the fact, and a confident
explanation is not evidence that the explanation is what actually drove the
decision. It is extremely useful for debugging and audit. It is not proof.

**A failed log write never fails a filled order.** If the log cannot be written,
the tool still reports success and attaches a warning. An agent told its order
failed will place it again — so a lost log line would become a doubled
position, which is far worse than the missing line. The risk engine is the
safety mechanism; the log is observability.

## Paper trading

`REINS_MODE=paper` (the default) runs the same tools, the same risk engine and
the same agent against **real prices with simulated fills**. Nothing is signed
and nothing reaches the exchange.

Paper and live are swapped behind one interface, so an agent cannot tell which
one it is talking to — which is the point. A strategy that works on paper runs
unchanged on live.

### What the simulation models

- **Real book depth.** A large o