End-to-End Example

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

A complete example: wallet setup, prerequisites, and placing an order using USER_AGENT mode.

import { PerpsClient, getProviders, getAssets } from '@lifi/perps-sdk';
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
const perps = new PerpsClient({
  integrator: 'my-app',
  apiKey: 'your-api-key',
});

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

const { assets } = await getAssets(perps.client, { provider: 'hyperliquid' });
console.log(assets.map((a) => a.displaySymbol)); // ['BTC', 'ETH', 'SOL', ...]

// 3. Set up agent signing
await perps.setSigningMode(userAddress, 'hyperliquid', 'USER_AGENT');

// 4. Authorize (one-time) — checks which approvals are needed
const required = await perps.checkPrerequisites({
  provider: 'hyperliquid',
  address: userAddress,
});

if (!required.isReady) {
  // Sign only the actions that need user wallet approval
  const signedActions = await Promise.all(
    required.userPrerequisites.map(async (a) => ({
      action: a.action,
      typedData: a.typedData,
      signature: await walletClient.signTypedData({ ...a.typedData }),
    }))
  );

  // Submit user-signed actions + auto-sign agent actions
  await perps.executePrerequisites({
    provider: 'hyperliquid',
    address: userAddress,
    required,
    userSignedActions: signedActions,
  });
}

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

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