IRONFLOW
IRONBOXAPILIQUIDATIONSPRICINGDOCSGET_API_KEY
GET_API_KEY
GUIDES · 8 NOVEMBER 2026 · 6 MIN READ

Hyperliquid paper trading: test a bot without risking funds

A paper box is your own simulated Hyperliquid account with $10,000 and live prices. Your bot keeps running where it runs today and changes one URL: the base_url of the official Hyperliquid SDK. A box never places a real order.

CONTENTS
  1. The short version
  2. 1. Key, or skip it
  3. 2. Create the box
  4. 3. Trade it with the official SDK
  5. 4. What is simulated
  6. 5. What a box does not do
  7. 6. Paper box or testnet
  8. 7. Reset, limits and going live
  9. Questions
  10. Related guides
  11. References

The short version#

  • Setup: one POST, no key, and the box URL as the SDK's base_url.
  • Simulated: fees, funding, cross margin and liquidation, on live Hyperliquid books.
  • Perps only: main perp markets above $1M of 24 hour volume, at most 100.
  • No real orders: orders never reach Hyperliquid, and a box refuses anything signed for mainnet.
  • Testnet: a separate network with its own thin books. The differences are below.

1. Get a free key, or skip it#

Skip this for a 24-hour trial box, one per caller. A free key keeps your boxes: one email, no card. Use the key page or ask for one from code.

bash
curl -X POST https://api.ironflow.sh/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

2. Create the box#

bash
curl -X POST https://api.ironflow.sh/v1/ironbox \
  -H "Authorization: Bearer $IRONFLOW_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "grid-bot", "mode": "paper"}'

The box runs at once. No key? Drop the Authorization line. The part of the answer you need:

json
{
  "id": "ibx_3f9a0c7e12d4",
  "state": "running",
  "mode": "paper",
  "base_url": "https://api.ironflow.sh/box/ibxs_...",
  "starting_balance_usd": 10000
}

base_url is shown once. Keep it like a password: anyone with it can trade the box, and only the box. If you lose it, POST /v1/ironbox/{id}/rotate gives a new one.

3. Trade it with the official SDK#

Install the official Python SDK with pip install hyperliquid-python-sdk. This ran in production on 8 November 2026, with SDK 0.24.0:

python
from eth_account import Account
from hyperliquid.exchange import Exchange
BOX = "https://api.ironflow.sh/box/ibxs_..."
Exchange(Account.create(), BOX).market_open("BTC", True, 0.001)

To read the account back, keep the wallet and add Info with skip_ws=True:

python
from eth_account import Account
from hyperliquid.exchange import Exchange
from hyperliquid.info import Info

BASE_URL = "https://api.ironflow.sh/box/ibxs_..."

wallet = Account.create()
info = Info(BASE_URL, skip_ws=True)
exchange = Exchange(wallet, base_url=BASE_URL)

print(exchange.market_open("BTC", True, 0.001))
print(info.user_state(wallet.address))
  • Wallet: use a throwaway key from Account.create(). Never a funded key.
  • One wallet per box: the first signed action binds the box to that wallet. A later run with a new Account.create() gets User or API Wallet 0x... does not exist. Save the key, or call rotate with {"unbind": true}.
  • Signing: because base_url is not https://api.hyperliquid.xyz, the SDK signs for testnet, and that is what a box accepts.
  • Retries: nonces follow Hyperliquid's rules, so a retried request cannot fill twice.

Paper box$10,000, live prices, no signup. Start a paper box.

4. What is simulated#

Every answer carries "paper": true or the X-Ironflow-Paper header.

RuleOn a paper box
Market and IOC ordersFill on the next book after they arrive, walking levels at each level's price.
Limit ordersRest, then fill at their limit when a trade prints strictly through the limit or the book moves through it.
Order typesGTC, IOC, ALO, reduce-only, stop and take-profit. Stops and take-profits are reduce-only.
MarginCross only. 20x by default, or the market maximum if lower. update_leverage changes it.
LiquidationThe whole account closes at the book when it falls below maintenance margin. Equity stops at zero.
FundingHourly on the oracle price, longs paying on a positive rate.
Fees0.045% taker, 0.015% maker.
Order validationHyperliquid's tick, size and $10 rules, with Hyperliquid's error text.

Markets are the main perps with more than $1M of 24 hour volume, capped at 100 and updated hourly.

5. What a box does not do#

  • Refused with an error: spot, HIP-3, HIP-4 outcomes and isolated margin, and any market outside the list above.
  • No WebSocket. Without skip_ws=True the SDK's Info waits on one forever.
  • No market impact. Orders never reach Hyperliquid, so nobody trades against them and the real book does not react.
  • Data gaps: a market with no data for 5 seconds refuses new orders and pauses fills, funding and liquidation. The box shows the gap.

A paper result is an estimate from real order book and trade data. Live results can differ.

6. Paper box or testnet#

Hyperliquid's testnet is a separate network at https://api.hyperliquid-testnet.xyz. Its faucet gives 1,000 mock USDC to addresses that have deposited on mainnet.

Paper boxTestnet
Prices and depthMainnet order books and trades, liveTestnet's own books and traders
Starting funds$10,000 when the box is created1,000 mock USDC from the faucet, after a mainnet deposit from the same address
MatchingSimulated against the live bookHyperliquid's engine, against other testnet orders
MarketsMain perps onlyPerps and spot
MarginCross onlyCross and isolated
WebSocketNonewss://api.hyperliquid-testnet.xyz/ws
SigningTestnet signature, from the SDK with no changeTestnet signature

Depth is the main difference for a strategy test. On 8 November 2026 the top 20 levels on both sides of the BTC book held about $13,000 on testnet and about $11.8 million on mainnet, the book a box fills against.

Use a box to see how a strategy behaves on real prices. Use testnet for what a box refuses: spot, isolated margin and WebSocket flows.

7. Reset, limits and going live#

  • Results: GET /v1/ironbox/{id} shows equity, profit, fees, funding, positions, fills and data gaps.
  • Reset: POST /v1/ironbox/{id}/reset restores the balance and clears positions, orders and fills.
  • Idle: a box idle for 30 days is stopped. Your next call resumes it, and it still counts toward your limit.
  • Batches: at most 50 orders.
PlanPaper boxes/exchange per min/info per minOpen orders
Free3120300100
Explorer56001,200500
Builder101,2002,4001,000
Enterprise25CustomCustomCustom

Rates are per box. To go live, set base_url back to https://api.hyperliquid.xyz and sign with your own key, which the SDK then signs for mainnet. Never use a funded key with a box.

Questions#

Does Hyperliquid have paper trading?#

Hyperliquid's own test environment is its testnet, a separate network with mock USDC and its own order books. An Ironflow paper box is a simulated account on mainnet prices, reached with the official Hyperliquid SDK.

How do I test a Hyperliquid bot without risking funds?#

Create a paper box, no key needed, and set the official SDK's base_url to the box URL. The bot gets $10,000 of simulated USDC and live prices. Use a throwaway wallet from Account.create() and never a funded key.

Does a paper box place real orders?#

No. Orders stay inside the simulator and never reach Hyperliquid, and a box refuses anything signed for mainnet.

Are fees, funding and liquidation simulated?#

Yes. Fees are 0.045% taker and 0.015% maker, funding is paid hourly on the oracle price, and the whole account is closed at the book when it falls below maintenance margin.

Which markets can I paper trade?#

Main Hyperliquid perps with more than $1M of 24 hour volume, at most 100 markets, updated hourly. Spot, HIP-3, HIP-4 outcomes and isolated margin are refused with an error.

How is a paper box different from Hyperliquid testnet?#

A box fills against live mainnet books and starts with $10,000, for perps with cross margin. Testnet is a separate network with its own thin books and 1,000 mock USDC after a mainnet deposit, and it also has spot, isolated margin and a WebSocket.

Does a paper box work with Freqtrade, CCXT or Hummingbot?#

We test the official Python SDK, version 0.24.0. A box answers /info and /exchange in Hyperliquid's format and has no WebSocket. We have not tested other clients.

What does a paper box cost?#

Nothing. With no key you get one 24-hour trial box. A free key keeps 3 boxes, Explorer 5, Builder 10 and Enterprise 25.

Related guides#

  • Hyperliquid candles and OHLCV data: the 5000 candle limit and older history
  • Hyperliquid funding rates: formula, history and API
  • Hyperliquid API rate limits explained
  • Hyperliquid historical data: API, S3 archive, SQL and free downloads

References#

  • Ironflow docs: Ironbox. Every endpoint, limit and error code for a paper box.
  • hyperliquid-dex/hyperliquid-python-sdk. The official Python SDK used above.
  • Hyperliquid docs: Testnet faucet. The mock USDC amount and the mainnet deposit rule.
  • Hyperliquid docs: API. Mainnet and testnet URLs.

A paper box takes one POST and no signup. Start a paper box and point your bot at it.

ON THIS PAGE
  1. The short version
  2. 1. Key, or skip it
  3. 2. Create the box
  4. 3. Trade it with the official SDK
  5. 4. What is simulated
  6. 5. What a box does not do
  7. 6. Paper box or testnet
  8. 7. Reset, limits and going live
  9. Questions
  10. Related guides
  11. References

Automated derivatives trading is high-risk: you can lose all of your funds. Ironflow is trading software, not financial advice, and never holds your funds. Not available to U.S. persons or in sanctioned jurisdictions. See Risk Disclosure.

Not affiliated with Hyperliquid or Pear Protocol.

IRONFLOW

© 2026 IRONFLOW

Product

IronboxAPI and MCPPricingNodesTerminal

Data

Live liquidationsLiquidation mapLiquidation heatmapHIP-4 outcomesDatasets

Developers

DocsGuidesFree API keyStatusGitHub

Company

TermsPrivacyRiskAcknowledgements