End-to-End Example

Complete trading example: wallet setup, account setup, and placing an order

A complete Hyperliquid example: wallet setup, one-time account setup, and an order signed by the SDK-managed agent.

import { PerpsClient, getProviders, getMarkets } from '@lifi/perps-sdk';
import { hyperliquidProvider } from '@lifi/perps-sdk-provider-hyperliquid';
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { arbitrum } from 'viem/chains';

// --- Wallet setup (viem with private key) ---
const account = privateKeyToAccount('0xYOUR_PRIVATE_KEY');
const walletClient = createWalletClient({
  account,
  chain: arbitrum,
  transport: http(),
});
const userAddress = account.address;

// --- Wallet setup (wagmi — browser) ---
// import { useWalletClient, useAccount } from 'wagmi';
//
// const { data: walletClient } = useWalletClient();
// const { address: userAddress } = useAccount();

// 1. Create the client and attach the user wallet (used only for setup actions).
//    Register the provider plugin so per-user reads and actions (checkSetup,
//    placeOrder, ...) can resolve the venue; without it they throw.
const perps = new PerpsClient({
  integrator: 'my-app',
  apiKey: 'your-api-key',
  providers: [hyperliquidProvider()],
});
perps.setUserWallet(walletClient);

// 2. Fetch available providers and markets
const { providers } = await getProviders(perps.client);
console.log(providers.map((p) => p.name)); // ['Hyperliquid', ...]

const { markets } = await getMarkets(perps.client, { provider: 'hyperliquid' });
console.log(markets.map((m) => m.baseAsset.displaySymbol)); // ['BTC', 'ETH', 'SOL', ...]

// 3. One-time setup: check, then run each outstanding step. The user's wallet
//    signs APPROVE_AGENT (and any other still-pending setup actions); after this
//    completes the SDK-managed agent is on-chain and trading proceeds without
//    further wallet prompts.
const required = await perps.checkSetup({
  provider: 'hyperliquid',
  address: userAddress,
});

if (!required.isReady) {
  // executeProviderSetupAction picks the right signing path per step (EIP-712,
  // EVM tx, or Lighter's hybrid WASM+EIP-191) and submits it, using the user
  // wallet above. Run the steps in descriptor order.
  for (const step of required.setup) {
    await perps.executeProviderSetupAction({
      provider: 'hyperliquid',
      address: userAddress,
      step,
    });
  }
}

// 4. Place an order — agent signs automatically, no wallet popup.
const result = await perps.placeOrder({
  address: userAddress,
  provider: 'hyperliquid',
  market: { marketId: 'BTC', categoryId: 'hyperliquid' },
  side: 'BUY',
  type: 'MARKET',
  size: '0.1',
  price: '95500.00',
  leverage: 10,
});

console.log(result.results);
// [{ action: 'placeOrder', success: true, orderId: '12345678' }]