End-to-End Example

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

A complete example: wallet setup, account setup (one-time), and placing an order. The user’s wallet is only invoked during setup — the order itself is signed by the SDK-managed agent.

import { PerpsClient, getProviders, getMarkets } 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 and attach the user wallet (used only for setup actions).
const perps = new PerpsClient({
  integrator: 'my-app',
  apiKey: 'your-api-key',
});
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 + sign + execute setup. 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) {
  // signProviderSetupAction picks the right signing path per step (EIP-712,
  // EVM tx, or Lighter's hybrid WASM+EIP-191). It uses the user wallet above.
  const signedActions = await Promise.all(
    required.setup.map((step) =>
      perps.signProviderSetupAction('hyperliquid', userAddress, step),
    ),
  );

  await perps.executeProviderSetup({
    provider: 'hyperliquid',
    address: userAddress,
    setup: required.setup,
    signedActions,
  });
}

// 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' }]