Skip to main content
GET
/
v2
/
polymarket
/
wallet
/
{address}
/
cluster
Connected wallets for an address (graph-based)
curl --request GET \
  --url https://api.predexon.com/v2/polymarket/wallet/{address}/cluster \
  --header 'x-api-key: <api-key>'
{
  "seed": "<string>",
  "siblings": [
    {
      "address": "<string>",
      "confidence": 50,
      "min_hops": 123,
      "evidence": {}
    }
  ],
  "computed_at": 123
}
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 a 200 OK or a 202 Accepted depending on cache state. Clients must handle both.
Returned on a fresh cache hit. The body is the full WalletClusterResponse.
{
  "seed": "0x89b5cdaaa4866c1e738406712012a630b4078beb",
  "siblings": [
    {
      "address": "0x07e18557cf1b62b5b613359badb39bbb8df93fb4",
      "confidence": 100,
      "min_hops": 2,
      "evidence": {
        "hops": { "out": 2, "in": 3 },
        "bidirectional": true,
        "class": null,
        "is_verified_trader": true,
        "direct_flow": [
          { "amount_str": "10000000", "tx_count": 1, "direction": "out" }
        ],
        "shared_peers": {
          "destinations": [],
          "sources": [{ "addr": "0xabc..." }],
          "count": 31
        }
      }
    }
  ],
  "computed_at": 1779154544
}
Why 202? Hub-wallet clusters can take 60–180 seconds to compute (a popular seed can reach tens of thousands of wallets) - far longer than any sane HTTP timeout. We compute out-of-band and write the result to a Postgres cache; the next call after Retry-After returns 200 from cache.

​
Evidence sub-fields

The evidence object is free-form, but typical sibling entries include:
FieldDescription
hops{out, in} BFS depths from seed to sibling on each direction of the transfer graph.
bidirectionaltrue when seed and sibling have sent funds both ways.
direct_flowArray of direct USDC/pUSD/CTF transfers with amount_str, tx_count, and direction.
shared_peersLow-degree wallets (degree < 50) that both seed and sibling transacted with. count ≥ 2 is a strong signal.
same_signerCryptographic match - sibling is controlled by the same EOA as the seed.
same_x_usernameSelf-asserted match - sibling set the same X / Twitter handle.
shared_first_funderBoth seed and sibling were initially funded by the same small wallet.
is_verified_traderSibling has trading activity on Polymarket.
classWallet classification (magic_link, contract, etc.) or null.
A sibling at confidence: 100 typically means bidirectional direct flow + verified trader + ≥2 shared peers, or an identity-proof match.

​
How siblings are discovered

  1. 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).
  2. Identity proofs - wallets sharing the seed’s cryptographic signer or self-asserted X username.
  3. Shared-peer discovery - wallets that both seed and the candidate transacted with through a small (degree < 50) intermediary.
  4. 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_cluster table) 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.
ConstraintValue
min_confidence0–100 (default 70)
limit1–1000 (default 50)
import time, requests

def get_cluster(addr, min_conf=70, limit=50, max_wait=300):
    deadline = time.time() + max_wait
    while time.time() < deadline:
        r = requests.get(
            f"https://api.predexon.com/v2/polymarket/wallet/{addr}/cluster",
            params={"min_confidence": min_conf, "limit": limit},
            headers={"x-api-key": API_KEY},
        )
        if r.status_code == 200:
            return r.json()
        if r.status_code == 202:
            retry = int(r.headers.get("Retry-After", 30))
            time.sleep(retry)
            continue
        r.raise_for_status()
    raise TimeoutError(f"Cluster for {addr} not ready within {max_wait}s")

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
address
string
required

Seed wallet address (proxy or signer).

Query Parameters

​
min_confidence
integer
default:70

Minimum confidence to include (default 70 = strong-only).

Required range: 0 <= x <= 100
​
limit
integer
default:50

Max siblings to return.

Required range: 1 <= x <= 1000
​
recompute
boolean
default:false

Kick off a fresh background BFS even if a cached result exists.

Response

Successful Response

Connected wallets for a seed wallet.

​
seed
string
required

Seed wallet address

​
siblings
ClusterSiblingEntry · object[]
required

Top sibling wallets by confidence

​
computed_at
integer | null

Unix timestamp when this cluster was last computed