Overview
Placing a trade through the Provider API requires two layers of authentication:
- API key — authenticates your request to the Provider API
- Wallet signature — authorizes the trade on the underlying DEX
This guide walks through placing a market buy on Hyperliquid. The flow for Aster is nearly identical.
We recommend starting on testnet first. Prefix all URLs with /v1/testnet/ instead of /v1/. See the Testnet Guide for setup. Step 1: Choose a Market
First, find the market you want to trade:
curl -s -H "X-API-Key: $API_KEY" \
https://api.perps.studio/v1/perps/hyperliquid/markets/ETH | jq
symbol, minSize, pricePrecision, and maxLeverage from the response.
Step 2: Set Up Your Wallet
Hyperliquid
Hyperliquid uses an agent wallet (also called an API wallet) for programmatic trading. This is a separate private key that your main wallet approves to trade on its behalf.
- Go to app.hyperliquid.xyz and connect your main wallet
- Navigate to API > Approve Agent
- Enter your agent wallet’s public address and approve the transaction
- Store the agent private key securely
Aster DEX
Aster uses a similar EIP-712 signer approval flow:
- Go to app.aster.finance and connect your main wallet
- Navigate to account settings and approve a signing key
- The signing key can then authorize trades
Step 3: Set Leverage
Before trading, set your desired leverage for the market:
curl -X POST -H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
https://api.perps.studio/v1/perps/hyperliquid/leverage \
-d '{
"symbol": "ETH",
"leverage": 10,
"wallet": "0xYourMainWallet",
"signature": "0x...",
"nonce": 1712000000000
}'
Step 4: Place a Market Order
curl -X POST -H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
https://api.perps.studio/v1/perps/hyperliquid/orders \
-d '{
"symbol": "ETH",
"side": "buy",
"type": "market",
"size": "0.1",
"wallet": "0xYourMainWallet",
"signature": "0x...",
"nonce": 1712000000000
}'
{
"orderId": "1234567890",
"status": "filled",
"symbol": "ETH",
"side": "buy",
"type": "market",
"size": "0.1",
"filledSize": "0.1",
"avgPrice": "3250.50"
}
Step 5: Check Your Position
curl -s -H "X-API-Key: $API_KEY" \
https://api.perps.studio/v1/perps/hyperliquid/account/0xYourWallet/positions | jq
[
{
"symbol": "ETH",
"side": "long",
"size": "0.1",
"entryPrice": "3250.50",
"markPrice": "3255.00",
"unrealizedPnl": "0.45",
"leverage": "10",
"liquidationPrice": "2930.00"
}
]
Step 6: Close the Position
To close, place an opposite-side market order with reduceOnly: true:
curl -X POST -H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
https://api.perps.studio/v1/perps/hyperliquid/orders \
-d '{
"symbol": "ETH",
"side": "sell",
"type": "market",
"size": "0.1",
"reduceOnly": true,
"wallet": "0xYourMainWallet",
"signature": "0x...",
"nonce": 1712000000001
}'
Order Types
| Type | Description | Required Fields |
|---|
market | Execute at best available price | symbol, side, size |
limit | Execute at specified price or better | symbol, side, size, price |
stop_market | Market order triggered at stop price | symbol, side, size, triggerPrice |
stop_limit | Limit order triggered at stop price | symbol, side, size, price, triggerPrice |
For Hyperliquid market orders, the Provider API uses FrontendMarket time-in-force (TIF) as required by the HIP-4 specification. Never use Gtc for market orders on Hyperliquid.
Common Errors
| Error | Cause | Fix |
|---|
INSUFFICIENT_MARGIN | Not enough USDC in account | Deposit more collateral |
SIGNATURE_ERROR | Bad wallet signature | Verify agent is approved and nonce is fresh |
SIZE_TOO_SMALL | Order size below minimum | Check minSize in market info |
MAX_LEVERAGE_EXCEEDED | Leverage too high | Reduce leverage or check market max |
