Quickstart

npm install copytrading

import { CopyTradingClient, createWalletAuthHeaders } from 'copytrading'

const client = new CopyTradingClient({
  baseUrl: API_URL,
  apiKey: PARTNER_KEY,
  // Owner-scoped routes need the user's signature too. Build this ONCE and
  // reuse it — it holds the monotonic timestamp counter that prevents replay
  // rejections.
  getAuthHeaders: createWalletAuthHeaders({ address: userAddress, signer: personalSigner }),
})

// 1. What can you offer? Entitlements are per-partner, so ask rather than assume.
const venues = await client.listVenues()

// 2. Who is worth copying? Graded for copyability, not ranked by PnL.
//    Clean by default — only leaders that pass the gates. Pass
//    { mirrorableOnly: false } only for a "check any wallet" surface, where
//    the gated-out entries and their assessment.reasons are the answer.
const leaders = await client.listLeaders({ venue: venues[0].id })

// 3. Create the agent.
const { agentId } = await client.createAgent({
  venue: venues[0].id,
  smartAccountAddress: userAddress,
  leaderWalletAddress: leaders[0].address,
  riskConfig: { maxUsd: '500', copyPercent: 10 },
})

// 4. One call, every venue. Walks whatever steps that venue needs.
await client.activate(agentId, signer)

// 5. Same feed shape everywhere.
const { executions } = await client.listExecutions(agentId)

import { CopyTradingClient, PerpsCopyClient } from 'copytrading'

const perps = new PerpsCopyClient({
  api: client,
  signer: { signTypedData: (payload) => wallet.signTypedData(payload) },
})

// 1. pick a leader
const strategies = await client.listStrategies(0)

// 2. create the agent, sign the Hyperliquid approvals, submit them
const { agentId } = await perps.activate({
  smartAccountAddress: userAddress,
  strategyId: 'perps-copytrade-hyperliquid',
  leaderWalletAddress: '0x…',
  maxUsd: '1000', // per-trade cap
  copyPercent: '100', // share of the leader's size, whole percent 0–100
  maxLeverage: 3,
})

// 3. show the user what it did
const { executions } = await client.listExecutions(agentId)