Why Use Testnet?
Testnet lets you:
- Test order placement and cancellation without risking real funds
- Validate your signing and authentication flow
- Debug edge cases (insufficient margin, invalid parameters) safely
- Build and demo integrations before going live
Quick Setup
Get Testnet Tokens
Visit the testnet faucet for your provider:Connect your wallet and claim testnet USDC. Set Up Agent Wallet on Testnet
Approve an agent wallet on the testnet UI, just like you would on mainnet. The agent address can be the same key you use for mainnet.
Use the Testnet URL Prefix
Add /testnet/ after /v1/ in all your API calls:# Mainnet
https://api.perps.studio/v1/perps/hyperliquid/markets
# Testnet
https://api.perps.studio/v1/testnet/perps/hyperliquid/markets
Full Example: Testnet Trading
const BASE = "https://api.perps.studio/v1/testnet";
// 1. List testnet markets
const markets = await fetch(`${BASE}/perps/hyperliquid/markets`, {
headers: { "X-API-Key": API_KEY },
}).then((r) => r.json());
console.log(`${markets.length} testnet markets available`);
// 2. Set leverage on testnet
await fetch(`${BASE}/perps/hyperliquid/leverage`, {
method: "POST",
headers: {
"X-API-Key": API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
symbol: "ETH",
leverage: 5,
wallet: "0xYourWallet",
signature: "0x...",
nonce: Date.now(),
}),
});
// 3. Place a testnet order
const order = await fetch(`${BASE}/perps/hyperliquid/orders`, {
method: "POST",
headers: {
"X-API-Key": API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
symbol: "ETH",
side: "buy",
type: "market",
size: "1",
wallet: "0xYourWallet",
signature: "0x...",
nonce: Date.now(),
}),
}).then((r) => r.json());
console.log("Testnet order:", order);
// 4. Check testnet position
const positions = await fetch(
`${BASE}/perps/hyperliquid/account/0xYourWallet/positions`,
{ headers: { "X-API-Key": API_KEY } },
).then((r) => r.json());
console.log("Testnet positions:", positions);
Switching Between Testnet and Mainnet
The cleanest approach is to use a configurable base URL:
const NETWORK = process.env.NETWORK ?? "mainnet";
const BASE = NETWORK === "testnet"
? "https://api.perps.studio/v1/testnet"
: "https://api.perps.studio/v1";
// All your code uses BASE -- no other changes needed
const markets = await fetch(`${BASE}/perps/hyperliquid/markets`, {
headers: { "X-API-Key": API_KEY },
}).then((r) => r.json());
Use environment variables to toggle between testnet and mainnet. This way, your code stays identical across environments.
