Reins

Reins

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

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.

The source is on GitHub: 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.

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

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

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 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:

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 order walks levels and pays real slippage instead of filling entirely at the touch.
• Partial fills when the book is too thin inside the limit price.
• Taker and maker fees at Hyperliquid's base tier (0.045% / 0.015%), plus any builder fee, so the equity curve is net of what trading actually costs.
• **Resting orders that only fill when the market trades strictly *through* them**, never merely to them. At your own price you are behind a queue this simulation cannot see; assuming a fill there is the most common way a paper equity curve lies.
• Fills between polls. Each call checks resting orders against the one-minute candles printed since they were placed, not just the book at that moment, and fills them at the minute the market first went through. Cancelling an order that already filled is refused, as the exchange would. Before this, the demo agent's breakout bid went unfilled under a dip that lasted two minutes, and it then cancelled an order Hyperliquid would already have filled.

What it does not model

The first five flatter the result; the last two can miss a fill either way. All of them are listed rather than buried:

• Latency — fills are priced off the book as it was when the tool was called
• Market impact — your order never moves the price or removes liquidity
• Funding payments on perps
• Slippage past a stop inside a minute already gone — a stop found triggered in a past candle fills at its trigger, or at the candle's open if the market gapped through it. One triggered right now walks the real book.
• Mark price — Hyperliquid triggers stops on the mark price; paper uses traded prices, which can differ briefly
• The minute an order was placed in — candles are only counted from the first minute that opened after it, so a dip in that same minute is missed
• Orders resting longer than about three days — only the latest 5000 one-minute candles are available, so older stretches go unchec