Trade PerpNow with the Hyperliquid Python SDK

Configure the Hyperliquid Python SDK for PerpNow testnet and submit a first order.

Updated 2026-11-05

Use the testnet endpoint

PerpNow exposes a Hyperliquid-compatible API on a public testnet. In most SDK-based clients, the important configuration is the PerpNow base URL rather than the upstream Hyperliquid endpoint. Set base_url="https://perpnow.xyz"; for the official Python SDK use testnet settings (is_mainnet = false). Do not send a real-value wallet workflow to mainnet: PerpNow test balances have no monetary value.

from hyperliquid.info import Info
info = Info("https://perpnow.xyz", skip_ws=True)
print(info.l2_snapshot("BTC"))

The read-only Info client can fetch market metadata and books through /info. The signed trading client uses /exchange. See the API and signing documentation and the BTC market.

Fund a test account

Create a wallet or use the site's demo account, then request test USDC from POST https://perpnow.xyz/faucet with JSON such as {"user":"0xYourAddress"}. Faucet limits apply; the endpoint can return a rate-limit response when a claim is not available. Test USDC is for exercising the testnet only, not a deposit or redeemable asset.

Approve an agent key

For safer automation, use a separate agent/API wallet. The primary wallet signs an approveAgent action that authorizes the agent to trade. User-signed actions use the EIP-712 domain HyperliquidSignTransaction, chain ID 421614 (hex 0x66eee); the action carries signatureChainId: "0x66eee" and hyperliquidChain: "Testnet". The official SDK's approve_agent helper fills these signing fields. Keep private keys out of source files and logs.

{"type":"approveAgent","hyperliquidChain":"Testnet",
 "signatureChainId":"0x66eee","agentAddress":"0x...",
 "agentName":"test-bot","nonce":1730000000000}

Nonces are millisecond timestamps and each nonce is used once per signer. Use the SDK helper rather than hand-building signatures unless you understand the EIP-712 domain and action encoding.

Place and cancel an order

After approval, the agent signs an order against the same PerpNow base URL. The exact method arguments can vary slightly by SDK release, but a limit GTC order follows this shape:

from hyperliquid.exchange import Exchange
exchange = Exchange(agent_account, "https://perpnow.xyz",
                    account_address=primary_address)
result = exchange.order("BTC", True, 0.001, 60000,
                        {"limit": {"tif": "Gtc"}})
oid = result["response"]["data"]["statuses"][0]["resting"]["oid"]
exchange.cancel("BTC", oid)

Check the returned status rather than assuming the order rested: it may fill immediately or be rejected. Decimal price and size formatting follows each market's precision rules. A GTC order can rest; IOC cancels its remainder, and ALO is post-only. The API also supports batch order, cancel and modify actions. For signed details and the current supported types, consult Docs.

Verify on-chain results

Orders are submitted as transactions and processed by the testnet validators. A successful response is not the only useful record: look for the transaction and resulting fills in Explorer, where fills link to their transaction hash. WebSocket streams can deliver book, trade and user-fill updates after commitment. If your application does not need streaming, SDK calls can use the HTTP endpoints directly.

Precision, response handling and streams

Before sending an order, read market metadata and use the market's size precision. PerpNow accepts decimal prices with at most five significant figures and no more than six minus the market's size-decimal count in fractional places; integer prices are accepted. Size decimals cannot exceed the market's configured size precision. Trailing fractional zeroes are not accepted. Format values before signing so that the action that is submitted is also the action you intend to authorize.

Responses can contain a resting order identifier, a fill, a cancellation, or an error status. Treat them as distinct outcomes in the client: save an order ID only when one is present, and inspect fills before assuming a position changed. For subsequent updates, subscribe to the market's book or trades and to the account's fills over wss://perpnow.xyz/ws. The stream reports committed updates; it complements, rather than replaces, handling the direct response to your signed request.

For environments that cannot maintain WebSocket connections, query order status or account history through the compatible API. Use bounded retries and avoid blindly replaying a signed action: nonces are single-use per signer, and a network timeout does not establish whether the original request was accepted. Check the order or transaction in Explorer before deciding whether a new action is needed.

This guide describes testnet integration only. Use the first-trade walkthrough for the demo UI flow, or read about hourly funding and risk checks.