Hyperliquid Testnet Quickstart: Test Funds, a First Order and 5 Mainnet Gotchas

#hyperliquid #python #web3 #tutorial

A condensed version of our full Hyperliquid testnet guide, which also covers HyperEVM gas, every error message we hit and a pre-mainnet checklist.

Hyperliquid's testnet lets you trade with mock USDC, so you can test order logic and signing before real money is involved. This is the short path: the addresses, test funds, one working order, and the five things that will break when you switch to mainnet.

1. The addresses you need

What	Testnet	Mainnet
API (info and exchange)	`https://api.hyperliquid-testnet.xyz`	`https://api.hyperliquid.xyz`
WebSocket	`wss://api.hyperliquid-testnet.xyz/ws`	`wss://api.hyperliquid.xyz/ws`
App	`app.hyperliquid-testnet.xyz`	`app.hyperliquid.xyz`
HyperEVM chain ID	998	999

In the Python SDK these are constants.TESTNET_API_URL and constants.MAINNET_API_URL.

2. Get test funds

Hyperliquid's faucet gives 1,000 mock USDC, once, and only to an address that has deposited on mainnet.
Circle's faucet (faucet.circle.com, network "HyperEVM Testnet") gives 20 USDC every 2 hours with no deposit needed. It lands on HyperEVM, so you deposit it into your trading account yourself.
Need HYPE for gas? Buy some with test USDC on the testnet HYPE/USDC market (@1035) and send it to 0x2222222222222222222222222222222222222222, which moves it to HyperEVM.

3. Place and cancel your first order

Approve an API wallet in the testnet app first (More → API), then set HL_SECRET_KEY to its key and HL_ACCOUNT_ADDRESS to your main testnet wallet. This places a buy far below the market, cancels it, and checks nothing is left open:

import os
import eth_account
from hyperliquid.exchange import Exchange
from hyperliquid.info import Info
from hyperliquid.utils import constants

URL = constants.TESTNET_API_URL
wallet = eth_account.Account.from_key(os.environ["HL_SECRET_KEY"])   # an API wallet made on testnet
account = os.environ["HL_ACCOUNT_ADDRESS"]                          # your testnet main wallet

info = Info(URL, skip_ws=True)
exchange = Exchange(wallet, URL, account_address=account)

price = round(float(info.all_mids()["BTC"]) * 0.5)   # far below the market, so it won't fill
result = exchange.order("BTC", True, 0.0003, price, {"limit": {"tif": "Gtc"}})

if result["status"] != "ok":
    raise SystemExit(result)
status = result["response"]["data"]["statuses"][0]
print("Order:", status)               # can be {"error": ...} even when status is "ok"

if "resting" in status:
    print("Cancel:", exchange.cancel("BTC", status["resting"]["oid"])["response"]["data"]["statuses"])
print("Open orders now:", info.open_orders(account))

Output from our run (your order ID will differ):

Order: {'resting': {'oid': 63428174589}}
Cancel: ['success']
Open orders now: []

Keep the per-order status check: a rejected order can still come back with a top-level "status": "ok".

4. Five things that break on mainnet

Market IDs. BTC is asset 0 on mainnet and 3 on testnet. Of the 207 perps on both networks, only one had the same ID. Look IDs up from meta and spotMeta every time.
Prices and liquidity. Testnet has its own books and traders, so prices drift from mainnet. Don't judge slippage or a strategy's results there.
Market settings. Maximum leverage differed on 101 of the 207 shared perps. Read limits from meta on the network you trade on.
API wallets and signatures. Approvals don't carry over, and a testnet signature won't work on mainnet. Approve a new API wallet on mainnet.
HyperEVM chain. Testnet is chain 998 and mainnet is 999. Check before you deploy a contract.

Going further

The full guide has the code for each difference, the exact error messages you'll hit on testnet and how to fix them, and a helper that catches price and size rounding errors before you send an order. For the API in general, see the Hyperliquid API guide.

DEV Community