Connected wallets for an address (graph-based)
Wallet Identity
Connected Wallets
Discover wallets connected to a seed address via on-chain transfers and identity proofs
GET
Connected wallets for an address (graph-based)
Returns sibling wallets discovered via the on-chain transfer graph (USDC, pUSD, CTF) plus identity-proof signals (shared signer, shared X username, shared first funder). Use this to surface likely-related accounts behind a single operator - alt wallets, hot/cold splits, multi-account farming patterns.
Requires Dev or Pro tier. This endpoint is not available on the Free tier.
Two response shapes
This endpoint can return either a200 OK or a 202 Accepted depending on cache state. Clients must handle both.
- 200 OK - cluster ready
- 202 Accepted - compute pending
Returned on a fresh cache hit. The body is the full
WalletClusterResponse.Evidence sub-fields
Theevidence object is free-form, but typical sibling entries include:
A sibling at
confidence: 100 typically means bidirectional direct flow + verified trader + ≥2 shared peers, or an identity-proof match.
How siblings are discovered
- Bidirectional BFS over the USDC / pUSD / CTF transfer graph from the seed (max depth 3, fanout 100, filters out high-degree pivots and shared-service wallets).
- Identity proofs - wallets sharing the seed’s cryptographic signer or self-asserted X username.
- Shared-peer discovery - wallets that both seed and the candidate transacted with through a small (
degree < 50) intermediary. - Scoring - combines hop distance, direct-flow tx count / amount, bidirectional flag, shared peers, shared first funder, verified-trader flag, and wallet class into a 0–100 confidence score.
Caching & limits
- Results persist in Postgres (
wallet_clustertable) and serve from cache for 24 hours. - After 24h the next request returns 202 and triggers a refresh.
- Background compute is deduplicated across API pods via Redis - only one BFS runs per seed at a time.
- A typical cache-hit response returns in ~100–500 ms including JSON encoding of up to 1000 siblings.
- Up to 1000 siblings are persisted per seed (sorted by confidence, descending). Direct bidirectional neighbors with multi-tx evidence are always prioritized - clients see the top 1000 strongest connections rather than the full graph.
Recommended client pattern
Authorizations
Path Parameters
Seed wallet address (proxy or signer).
Query Parameters
Minimum confidence to include (default 70 = strong-only).
Required range:
0 <= x <= 100Max siblings to return.
Required range:
1 <= x <= 1000Kick off a fresh background BFS even if a cached result exists.
