> ## Documentation Index
> Fetch the complete documentation index at: https://docs.predexon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connected Wallets

> Discover wallets connected to a seed address via on-chain transfers and identity proofs

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.

<Note>**Requires Dev or Pro tier.** This endpoint is not available on the Free tier.</Note>

## Two response shapes

This endpoint can return either a **`200 OK`** or a **`202 Accepted`** depending on cache state. **Clients must handle both.**

<Tabs>
  <Tab title="200 OK - cluster ready">
    Returned on a fresh cache hit. The body is the full `WalletClusterResponse`.

    ```json theme={null}
    {
      "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
    }
    ```
  </Tab>

  <Tab title="202 Accepted - compute pending">
    Returned when the cache is empty, stale (>24h old), or `recompute=true` was passed. Background BFS has been kicked off - retry after the indicated interval.

    ```http theme={null}
    HTTP/1.1 202 Accepted
    Retry-After: 60
    Content-Type: application/json

    {
      "status": "compute_pending",
      "retry_after_seconds": 60,
      "reason": "miss",
      "message": "Cluster compute is running in the background. Retry after the indicated interval to receive the full result."
    }
    ```

    `reason` values:

    | Value                   | Meaning                                                                        |
    | ----------------------- | ------------------------------------------------------------------------------ |
    | `miss`                  | Seed has never been computed; a background job was just spawned.               |
    | `stale`                 | Cached result is older than 24h; a refresh was spawned.                        |
    | `forced`                | Caller passed `recompute=true`.                                                |
    | `another_pod_computing` | A job for this seed is already running on another API pod (Redis-coordinated). |
  </Tab>
</Tabs>

<Warning>
  **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.
</Warning>

## Evidence sub-fields

The `evidence` object is free-form, but typical sibling entries include:

| Field                 | Description                                                                                                    |
| --------------------- | -------------------------------------------------------------------------------------------------------------- |
| `hops`                | `{out, in}` BFS depths from seed to sibling on each direction of the transfer graph.                           |
| `bidirectional`       | `true` when seed and sibling have sent funds both ways.                                                        |
| `direct_flow`         | Array of direct USDC/pUSD/CTF transfers with `amount_str`, `tx_count`, and `direction`.                        |
| `shared_peers`        | Low-degree wallets (`degree < 50`) that both seed and sibling transacted with. `count ≥ 2` is a strong signal. |
| `same_signer`         | Cryptographic match - sibling is controlled by the same EOA as the seed.                                       |
| `same_x_username`     | Self-asserted match - sibling set the same X / Twitter handle.                                                 |
| `shared_first_funder` | Both seed and sibling were initially funded by the same small wallet.                                          |
| `is_verified_trader`  | Sibling has trading activity on Polymarket.                                                                    |
| `class`               | Wallet 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.

| Constraint       | Value               |
| ---------------- | ------------------- |
| `min_confidence` | 0–100 (default 70)  |
| `limit`          | 1–1000 (default 50) |

## Recommended client pattern

```python theme={null}
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")
```


## OpenAPI

````yaml GET /v2/polymarket/wallet/{address}/cluster
openapi: 3.1.0
info:
  title: Predexon API
  description: Prediction market data aggregation and matching API
  version: 2.0.0
servers:
  - url: https://api.predexon.com
security:
  - apiKey: []
paths:
  /v2/polymarket/wallet/{address}/cluster:
    get:
      tags:
        - polymarket
      summary: Connected wallets for an address (graph-based)
      description: >-
        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). Confidence is 0-100; ≥70 indicates
        strong evidence. On a cache miss the endpoint returns 202 and computes
        the cluster in the background — the next call returns the full result.
      operationId: get_wallet_cluster_v2_polymarket_wallet__address__cluster_get
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
            description: Seed wallet address (proxy or signer).
            title: Address
          description: Seed wallet address (proxy or signer).
        - name: min_confidence
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 0
            description: Minimum confidence to include (default 70 = strong-only).
            default: 70
            title: Min Confidence
          description: Minimum confidence to include (default 70 = strong-only).
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 1000
            minimum: 1
            description: Max siblings to return.
            default: 50
            title: Limit
          description: Max siblings to return.
        - name: recompute
          in: query
          required: false
          schema:
            type: boolean
            description: Kick off a fresh background BFS even if a cached result exists.
            default: false
            title: Recompute
          description: Kick off a fresh background BFS even if a cached result exists.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletClusterResponse'
        '202':
          description: Compute in progress. Retry after the indicated interval.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
components:
  schemas:
    WalletClusterResponse:
      properties:
        seed:
          type: string
          title: Seed
          description: Seed wallet address
        siblings:
          items:
            $ref: '#/components/schemas/ClusterSiblingEntry'
          type: array
          title: Siblings
          description: Top sibling wallets by confidence
        computed_at:
          anyOf:
            - type: integer
            - type: 'null'
          title: Computed At
          description: Unix timestamp when this cluster was last computed
      type: object
      required:
        - seed
        - siblings
      title: WalletClusterResponse
      description: Connected wallets for a seed wallet.
    ErrorResponse:
      properties:
        error:
          type: string
          title: Error
        message:
          type: string
          title: Message
      type: object
      required:
        - error
        - message
      title: ErrorResponse
      description: Standard error response.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ClusterSiblingEntry:
      properties:
        address:
          type: string
          title: Address
          description: Sibling wallet address
        confidence:
          type: integer
          maximum: 100
          minimum: 0
          title: Confidence
          description: Confidence score 0-100
        min_hops:
          type: integer
          title: Min Hops
          description: Shortest path from seed to sibling
        evidence:
          type: object
          title: Evidence
          description: Evidence object for the sibling relation
      type: object
      required:
        - address
        - confidence
        - min_hops
        - evidence
      title: ClusterSiblingEntry
      description: One sibling wallet related to the seed via transfer-graph signals.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````