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

# Connections

> Find wallets connected to a given wallet by shared token activity, ranked by how many tokens they traded in common over the last 30 days.

Discover which other tracked wallets trade the same tokens as a given wallet. CabalSpy compares the tokens the wallet traded over the last 30 days against every other tracked wallet of the same type and returns those with overlap, ranked by how many tokens they share.

Use it to map clusters of wallets that move together, spot wallets that shadow a known KOL, or surface a network of related traders around one address.

<Tip>
  overlap\_score is the share of the source wallet tokens that the other wallet also traded, from 0 to 1. A higher shared\_tokens count and a higher overlap\_score mean a stronger connection. Results are sorted by shared\_tokens, highest first.
</Tip>

## Query Parameters

<ParamField query="blockchain" type="string" required>
  Chain of the wallet. One of solana, bnb, base, eth.
</ParamField>

<ParamField query="address" type="string" required>
  The source wallet address to find connections for.
</ParamField>

<ParamField query="limit" type="integer">
  Maximum number of connections to return. Omit to return all.
</ParamField>

<ParamField query="api_key" type="string" required>
  Your API key. Alternatively pass it as an Authorization Bearer header.
</ParamField>

## Usage Example

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.cabalspy.xyz/v1/wallets/connections?blockchain=solana&address=7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW&limit=20&api_key=YOUR_KEY"
  ```

  ```python Python theme={null}
  import requests

  params = {
      "blockchain": "solana",
      "address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
      "limit": 20, "api_key": "YOUR_KEY",
  }
  r = requests.get("https://api.cabalspy.xyz/v1/wallets/connections", params=params)

  for c in r.json()["data"]["connections"]:
      print(c["name"] or c["wallet_address"], "shared", c["shared_tokens"], "score", c["overlap_score"])
  ```

  ```javascript JavaScript theme={null}
  const p = new URLSearchParams({
    blockchain: "solana",
    address: "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
    limit: "20", api_key: "YOUR_KEY",
  });
  const res = await fetch(`https://api.cabalspy.xyz/v1/wallets/connections?${p}`);
  const { data } = await res.json();
  data.connections.forEach(c =>
    console.log(c.name || c.wallet_address, "shared", c.shared_tokens));
  ```
</CodeGroup>

## Response

<ResponseField name="success" type="boolean">
  True on success.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="data">
    <ResponseField name="wallet_address" type="string">
      The source wallet the connections were computed for.
    </ResponseField>

    <ResponseField name="blockchain" type="string">
      Requested chain.
    </ResponseField>

    <ResponseField name="connections" type="array">
      <Expandable title="connection, sorted by shared_tokens highest first">
        <ResponseField name="wallet_address" type="string">
          Address of the connected wallet.
        </ResponseField>

        <ResponseField name="name" type="string">
          Display name of the connected wallet (may be empty).
        </ResponseField>

        <ResponseField name="image_url" type="string">
          Avatar URL.
        </ResponseField>

        <ResponseField name="twitter" type="string">
          Twitter or X link.
        </ResponseField>

        <ResponseField name="type" type="string">
          Wallet type kol, smart or whale.
        </ResponseField>

        <ResponseField name="shared_tokens" type="integer">
          Number of tokens both wallets traded in the last 30 days.
        </ResponseField>

        <ResponseField name="overlap_score" type="number">
          Share of the source wallet tokens that the connected wallet also traded, from 0 to 1.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "wallet_address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
      "blockchain": "solana",
      "connections": [
        {
          "wallet_address": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
          "name": "Cupsey",
          "image_url": "https://cabalspy.xyz/images/9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin.png",
          "twitter": "https://x.com/cupseyy",
          "type": "kol",
          "shared_tokens": 18,
          "overlap_score": 0.375
        },
        {
          "wallet_address": "3Cx7Wm8yQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZbXX",
          "name": "",
          "image_url": "",
          "twitter": "",
          "type": "kol",
          "shared_tokens": 9,
          "overlap_score": 0.187
        }
      ]
    },
    "meta": {
      "request_id": "req_5162c7cf7f87",
      "cached": true,
      "cache_age_seconds": 120,
      "version": "1.0.0",
      "timestamp": "2026-07-06T11:01:57Z"
    }
  }
  ```
</ResponseExample>

## Errors

| Status | Code               | Meaning                               |
| ------ | ------------------ | ------------------------------------- |
| 400    | missing\_parameter | address is missing.                   |
| 400    | invalid\_parameter | blockchain missing or invalid.        |
| 401    | unauthorized       | API key missing.                      |
| 403    | forbidden          | API key invalid or credits exhausted. |
| 429    | rate\_limited      | Rate limit exceeded.                  |