Hyperliquid is a high-performance blockchain designed specifically for decentralized derivatives trading. It offers incredibly fast transaction processing, low fees, and a fully onchain open financial system.
This guide will walk you through setting up trading on Hyperliquid using Privy’s EVM wallets, focusing on how to securely authenticate and interact with the Hyperliquid API without ever exposing private keys.
The Privy SDKs are designed to be fully compatible with the Hyperliquid API, allowing you to build secure trading applications with ease.
Resources
Integrating with Hyperliquid
Setting up Hyperliquid with Privy in NodeJS
We’ll be using the Hyperliquid SDK with Privy’s ethers.js integration to interact with the Hyperliquid API.
1. Installation
First, install the necessary dependencies:
npm install @nktkas/hyperliquid @privy-io/server-auth ethers@latest
2. Initialize Privy Server SDK
Set up Privy’s server SDK to interact with your managed wallets:
import { PrivyClient } from '@privy-io/server-auth';
// Initialize Privy client with your API key
const privyClient = new PrivyClient('insert-your-app-id', 'insert-your-app-secret', {
walletApi: {
authorizationPrivateKey: 'insert-your-authorization-private-key' // Optional
}
});
3. Create Ethers Compatible Signer
Use Privy’s createEthersSigner
utility to create an ethers-compatible signer:
import { ethers } from 'ethers';
import { createEthersSigner } from '@privy-io/server-auth/ethers';
// Initialize your ethers provider
const provider = new ethers.JsonRpcProvider('https://base.llamarpc.com');
// Get your wallet from Privy
const walletId = 'insert-wallet-id';
const wallet = await privyClient.walletApi.getWallet({id: walletId});
const address = wallet.address;
// Create an ethers signer
const signer = createEthersSigner({
walletId,
address,
provider,
privyClient,
});
4. Initialize Hyperliquid SDK
Use the ethers signer to initialize the Hyperliquid client:
import * as hl from '@nktkas/hyperliquid';
// Create Hyperliquid transport and client
const transport = new hl.HttpTransport();
const client = new hl.ExchangeClient({
transport,
wallet: signer
});
const infoClient = new hl.InfoClient({ transport })
5. Check if Wallet has Account
Before trading, ensure the wallet has an account on Hyperliquid:
// Check if Hyperliquid account is active
const preTransferCheck = await infoClient.preTransferCheck({
user: wallet.address,
source: "<address-used-to-credit-account>",
});
if (!preTransferCheck.userExists) {
throw new Error("Hyperliquid account does not exist for this wallet.");
}
6. Getting Tradable Assets and Contexts
Before trading assets their metadata and contexts need to be fetched first:
// Get available assets
const metaAndCtx = await infoClient.metaAndAssetCtxs();
const meta = metaAndCtx[0];
const ctx = metaAndCtx[1];
// Find the asset index for BTC
const btcIndex = meta.universe.findIndex((asset) => asset.name === "BTC");
const universe = meta.universe[btcIndex];
const btcContext = ctx[btcIndex];
const price = formatPrice(
new BigNumber(btcContext.markPx).times(1.01),
universe.szDecimals,
);
const triggerPrice = formatPrice(
new BigNumber(btcContext.markPx).times(0.99),
universe.szDecimals,
);
const size = formatSize(
new BigNumber(15).div(btcContext.markPx),
universe.szDecimals,
);
7. Making Trades
Now you can use the client to place orders and interact with the Hyperliquid API:
// Place a market order
const orderResponse = await client.order({
orders: [
{
a: btcIndex, // Asset index
b: true, // Buy order
s: sz, // Size
r: false, // Not reduce-only
p: pxUp, // Price (0 for market order)
t: { trigger: { isMarket: true, tpsl: "tp", triggerPx: pxDown } }, // Market order
},
],
grouping: "na", // No grouping
});
console.log("Order placed:", orderResponse);
// Check open positions
const userState = await infoClient.clearinghouseState({ user: address });
console.log("Account state:", userState);
This approach keeps your wallet’s private keys secure by delegating all signing operations
to Privy’s secure API, while providing full compatibility with Hyperliquid’s trading features.
Setting up Hyperliquid with Privy in NodeJS
We’ll be using the Hyperliquid SDK with Privy’s ethers.js integration to interact with the Hyperliquid API.
1. Installation
First, install the necessary dependencies:
npm install @nktkas/hyperliquid @privy-io/server-auth ethers@latest
2. Initialize Privy Server SDK
Set up Privy’s server SDK to interact with your managed wallets:
import { PrivyClient } from '@privy-io/server-auth';
// Initialize Privy client with your API key
const privyClient = new PrivyClient('insert-your-app-id', 'insert-your-app-secret', {
walletApi: {
authorizationPrivateKey: 'insert-your-authorization-private-key' // Optional
}
});
3. Create Ethers Compatible Signer
Use Privy’s createEthersSigner
utility to create an ethers-compatible signer:
import { ethers } from 'ethers';
import { createEthersSigner } from '@privy-io/server-auth/ethers';
// Initialize your ethers provider
const provider = new ethers.JsonRpcProvider('https://base.llamarpc.com');
// Get your wallet from Privy
const walletId = 'insert-wallet-id';
const wallet = await privyClient.walletApi.getWallet({id: walletId});
const address = wallet.address;
// Create an ethers signer
const signer = createEthersSigner({
walletId,
address,
provider,
privyClient,
});
4. Initialize Hyperliquid SDK
Use the ethers signer to initialize the Hyperliquid client:
import * as hl from '@nktkas/hyperliquid';
// Create Hyperliquid transport and client
const transport = new hl.HttpTransport();
const client = new hl.ExchangeClient({
transport,
wallet: signer
});
const infoClient = new hl.InfoClient({ transport })
5. Check if Wallet has Account
Before trading, ensure the wallet has an account on Hyperliquid:
// Check if Hyperliquid account is active
const preTransferCheck = await infoClient.preTransferCheck({
user: wallet.address,
source: "<address-used-to-credit-account>",
});
if (!preTransferCheck.userExists) {
throw new Error("Hyperliquid account does not exist for this wallet.");
}
6. Getting Tradable Assets and Contexts
Before trading assets their metadata and contexts need to be fetched first:
// Get available assets
const metaAndCtx = await infoClient.metaAndAssetCtxs();
const meta = metaAndCtx[0];
const ctx = metaAndCtx[1];
// Find the asset index for BTC
const btcIndex = meta.universe.findIndex((asset) => asset.name === "BTC");
const universe = meta.universe[btcIndex];
const btcContext = ctx[btcIndex];
const price = formatPrice(
new BigNumber(btcContext.markPx).times(1.01),
universe.szDecimals,
);
const triggerPrice = formatPrice(
new BigNumber(btcContext.markPx).times(0.99),
universe.szDecimals,
);
const size = formatSize(
new BigNumber(15).div(btcContext.markPx),
universe.szDecimals,
);
7. Making Trades
Now you can use the client to place orders and interact with the Hyperliquid API:
// Place a market order
const orderResponse = await client.order({
orders: [
{
a: btcIndex, // Asset index
b: true, // Buy order
s: sz, // Size
r: false, // Not reduce-only
p: pxUp, // Price (0 for market order)
t: { trigger: { isMarket: true, tpsl: "tp", triggerPx: pxDown } }, // Market order
},
],
grouping: "na", // No grouping
});
console.log("Order placed:", orderResponse);
// Check open positions
const userState = await infoClient.clearinghouseState({ user: address });
console.log("Account state:", userState);
This approach keeps your wallet’s private keys secure by delegating all signing operations
to Privy’s secure API, while providing full compatibility with Hyperliquid’s trading features.
Setting up Hyperliquid with Privy in Python
The Python integration allows you to use Privy’s server-side wallet management with Hyperliquid’s Python SDK to build secure trading applications.
Installation
First, install the required dependencies:
pip install hyperliquid-python-sdk>=0.14.1 privy-eth-account
Make sure to use at least version 0.14.1 of the hyperliquid-python-sdk, as earlier versions use deprecated RPC methods that may not work correctly.
Initialize Privy
Set up the Privy client to interact with your managed wallets:
from privy_eth_account import PrivyHTTPClient
# Initialize your Privy client
client = PrivyHTTPClient(
app_id="YOUR_APP_ID",
app_secret="YOUR_APP_SECRET",
authorization_key="YOUR_AUTHORIZATION_KEY"
)
Create a Signer
Privy EVM wallets natively integrate with the Python eth-account library, so you can use it to create a signer that interacts with the Hyperliquid API.
from privy_eth_account import create_eth_account
# Create an account instance for a wallet
wallet_id = "insert-wallet-id"
wallet_address = "insert-wallet-address"
account = create_eth_account(client, wallet_address, wallet_id)
Set up the Hyperliquid Exchange Client
Now that you have a signer, you can set up the Hyperliquid exchange client:
from hyperliquid.exchange import Exchange
exchange = Exchange(account, base_url, account_address=wallet_address, perp_dexs=perp_dexs)
Making Trades
You can now use the exchange client to place orders and interact with the Hyperliquid API:
order_result = exchange.order("ETH", True, 0.2, 1100, {"limit": {"tif": "Gtc"}})
Conclusion
By combining Privy’s secure wallet infrastructure with Hyperliquid’s high-performance trading platform, you can build powerful trading applications without compromising on security. The custom signer approach allows you to leverage Privy’s key management while still benefiting from all the features of Hyperliquid’s API.
For more advanced features like subscription to real-time order book data or implementing complex trading strategies, refer to the Hyperliquid documentation.
Your application can now securely trade on Hyperliquid using Privy’s managed wallets!