> ## 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.

# Lookup

> Look up any wallet address across all chains and wallet types to check if CabalSpy tracks it and return its KOL, Smart or Whale profile.

Given just an address, this finds out whether CabalSpy tracks it and, if so, returns its profile plus which chain and category (kol, smart, whale) it belongs to. Use it to label an arbitrary address in your UI, for example to show a name and avatar next to a wallet that appears in a transaction feed.

<Tip>
  You do not pass a blockchain or type. The lookup searches all chains and types for you and returns the first match. Always check the found field, it is false when the address is not tracked.
</Tip>

## Query Parameters

<ParamField query="address" type="string" required>
  The wallet address to look up. Searched across every tracked chain and wallet type.
</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/lookup?address=7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW&api_key=YOUR_KEY"
  ```

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

  params = {"address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW", "api_key": "YOUR_KEY"}
  r = requests.get("https://api.cabalspy.xyz/v1/wallets/lookup", params=params)
  data = r.json()["data"]

  if data["found"]:
      print(data["name"], "-", data["type"], "on", data["blockchain"])
  else:
      print("Not tracked")
  ```

  ```javascript JavaScript theme={null}
  const p = new URLSearchParams({
    address: "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW", api_key: "YOUR_KEY",
  });
  const res = await fetch(`https://api.cabalspy.xyz/v1/wallets/lookup?${p}`);
  const { data } = await res.json();
  console.log(data.found ? `${data.name} (${data.type})` : "Not tracked");
  ```
</CodeGroup>

## Response

<ResponseField name="success" type="boolean">
  True on success. The request worked, regardless of whether the wallet was found.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="data">
    <ResponseField name="found" type="boolean">
      Whether the address is tracked by CabalSpy. When false, only found and wallet\_address are returned.
    </ResponseField>

    <ResponseField name="wallet_address" type="string">
      The looked up address.
    </ResponseField>

    <ResponseField name="name" type="string">
      Display name (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="telegram" type="string">
      Telegram link.
    </ResponseField>

    <ResponseField name="copytrade_link" type="string">
      Copytrade link.
    </ResponseField>

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

    <ResponseField name="blockchain" type="string">
      Chain where it was found.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Native currency of that chain.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Found theme={null}
  {
    "success": true,
    "data": {
      "found": true,
      "wallet_address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
      "name": "Maze",
      "image_url": "https://cabalspy.xyz/images/7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW.png",
      "twitter": "https://x.com/MazeCCC",
      "telegram": "",
      "copytrade_link": "https://t.me/WizGandalfBot?start=r-U7TSHAWUWN-7j7AA",
      "type": "kol",
      "blockchain": "solana",
      "currency": "SOL"
    },
    "meta": {
      "request_id": "req_5162c7cf7f87",
      "cached": false,
      "cache_age_seconds": 0,
      "version": "1.0.0",
      "timestamp": "2026-07-06T11:01:57Z"
    }
  }
  ```

  ```json Not found theme={null}
  {
    "success": true,
    "data": {
      "found": false,
      "wallet_address": "SomeUntrackedAddress1111111111111111111111"
    },
    "meta": {
      "request_id": "req_9aa1917e433b",
      "cached": false,
      "cache_age_seconds": 0,
      "version": "1.0.0",
      "timestamp": "2026-07-06T11:02:10Z"
    }
  }
  ```
</ResponseExample>

## Errors

A wallet not found is not an error, you get 200 with found false. The errors below concern the request itself.

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