Recipe — Copy flow

The copy flow is two products composed: the Intelligence API decides what is worth copying, the copytrading SDK moves how it gets copied. A flow that skips the first half ships a venue leaderboard with a buy button; the vetting is what makes it a product.

The shape of the flow

1. Browse — a Leaderboard screen (trader-board / copy/strategies).
2. Vet — a Trader page (wallet-overview for spot, perp-wallet for Hyperliquid).
3. Decide the size — copy-plan / perp-copy-decision (below).
4. Activate — the SDK's five calls (Quickstart).
5. Feed — listExecutions + webhooks, skips included.

Vet before you copy

Beyond the dossier, two endpoints answer the sizing question directly:

POST /v1/copy-plan
{ "wallet": "0xFOLLOWER…", "leadWallet": "0xLEADER…", "chain": "eth" }
# → { copy, plan: { capitalPct, allocationUsd, perPositionCapPct, exclusions }, warnings[] }

POST /v1/perp-copy-decision
{ … leverage/liq/funding inputs … }
# → { copy, maxLeverage, sizeFactor, liqDistancePct, fundingCostDaily, flags[] }

copy-plan's warnings[] and exclusions are written to be rendered in the confirmation sheet — the user should see why the suggested size is what it is. Adding a second leader? POST /v1/copy-overlap says whether the new one is redundant against the copies they already run.

Execute with the SDK

import { CopyTradingClient, createWalletAuthHeaders } from 'copytrading'

const client = new CopyTradingClient({
  baseUrl: API_URL,
  apiKey: PARTNER_KEY,
  getAuthHeaders: createWalletAuthHeaders({ address: userAddress, signer: personalSigner }),
})

const venues = await client.listVenues()
const leaders = await client.listLeaders({ venue: 'hyperliquid-perps' })
const { agentId } = await client.createAgent({ venue: 'hyperliquid-perps', smartAccountAddress: userAddress, leaderWalletAddress: leaders[0].address, riskConfig: { maxUsd: '500', copyPercent: 10 } })
await client.activate(agentId, signer)
const { executions } = await client.listExecutions(agentId)

The full walkthrough — signer requirements, spot smart sessions, webhooks — is the Copy Trading Quickstart; the SDK also ships INTEGRATE.md, a single self-contained file for AI coding agents.

UX rules

1. Render assessment.reasons on every leader. listLeaders is the board after copyability gates; the plain-language reasons are the product. assessment.evidence tells you whether the verdict rests on real trade history (closed-trades) or only the venue's own figures (venue-only) — surface the difference.
2. Show skipped executions. status: 'skipped' + skipReason (slippage_exceeded, edge_exhausted, …) is the system refusing a losing trade. A labelled skip reads as protection; a silent gap reads as a bug.
3. expired ≠ paused. Expired credentials (spot sessions, Polymarket) need a fresh activate() — a resume button will not work. Route expired agents to re-activation and subscribe to the agent.session_expiring webhook.
4. Thin perp profiles carry their own why. When perp-wallet returns coverage.reason !== 'ok', show coverage.note in the vetting sheet — an honest "too new to judge" prevents a bad copy better than a blank card.