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

# Wallet lookup

> GET /v1/wallets/lookup: which of your users verified a wallet, proven by an on-chain payment from it.

Which of your users owns a wallet. A wallet belongs to a CabalSpy ID user once they proved it with an on-chain payment from that wallet, so the answer is verified, not self-reported.

Use it to attach a name and an X profile to a wallet you see in a trade, a leaderboard or a holder list. The address is matched on every chain, EVM addresses case-insensitively.

## Query Parameters

<ParamField query="address" type="string" required>
  The wallet address to look up.
</ParamField>

<ParamField query="scope" default="instance" type="string">
  `global` searches every CabalSpy ID user. Enterprise plan only.
</ParamField>

<ParamField query="instance" type="string">
  Your Instance ID. Only needed when your account has several instances.
</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-id.cabalspy.xyz/v1/wallets/lookup?address=7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW" \
    -H "Authorization: Bearer YOUR_KEY"
  ```

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

  r = requests.get("https://api-id.cabalspy.xyz/v1/wallets/lookup",
                   params={"address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW"},
                   headers={"Authorization": "Bearer YOUR_KEY"})
  if r.status_code == 404:
      print("not a verified wallet of your users")
  else:
      d = r.json()["data"]
      print(d["owner"]["username"], d["wallet"]["chains"])
  ```

  ```javascript JavaScript theme={null}
  const p = new URLSearchParams({ address: "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW" });
  const res = await fetch(`https://api-id.cabalspy.xyz/v1/wallets/lookup?${p}`, {
    headers: { Authorization: "Bearer YOUR_KEY" },
  });
  const body = await res.json();
  if (body.success) console.log(body.data.owner.username, body.data.wallet.chains);
  ```
</CodeGroup>

## Response

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

<ResponseField name="data" type="object">
  <Expandable title="data">
    <ResponseField name="address" type="string">
      The address you asked for.
    </ResponseField>

    <ResponseField name="verified" type="boolean">
      Always true on success.
    </ResponseField>

    <ResponseField name="wallet" type="object">
      <Expandable title="wallet">
        <ResponseField name="address" type="string">
          Wallet address as verified.
        </ResponseField>

        <ResponseField name="family" type="string">
          solana or evm.
        </ResponseField>

        <ResponseField name="chains" type="array">
          Chains the wallet is verified on.
        </ResponseField>

        <ResponseField name="verified_at" type="string">
          When the wallet was verified.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="owner" type="object">
      The owner's profile, the same fields as [Profile](/cabalspy-id/profile) without the wallets list: csid\_id, username, name, image\_url, bio, twitter, telegram, x, kol, profile\_url, joined\_at. `twitter`, `bio` and `x` are null for users without X.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
      "verified": true,
      "wallet": {
        "address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
        "family": "solana",
        "chains": ["solana"],
        "verified_at": "2026-10-09T14:21:07Z"
      },
      "owner": {
        "csid_id": "0b7c4a52-3f1e-4f43-9d0a-2b5e7c1d9a11",
        "username": "MazeCCC",
        "name": "Maze",
        "image_url": "https://pbs.twimg.com/profile_images/.../photo.jpg",
        "bio": "onchain since 2020",
        "twitter": "https://x.com/MazeCCC",
        "telegram": "",
        "x": {
          "id": "1440000000000000000",
          "followers": 48210,
          "following": 812,
          "verified": true,
          "verified_type": "blue"
        },
        "kol": { "badge": true, "since": "2026-10-10T12:00:00Z" },
        "profile_url": "https://id.cabalspy.xyz/u/MazeCCC",
        "joined_at": "2026-10-09T14:02:51Z"
      }
    },
    "meta": {
      "request_id": "req_5162c7cf7f87",
      "cached": false,
      "cache_age_seconds": 0,
      "version": "v1",
      "timestamp": "2026-10-13T08:04:11Z"
    }
  }
  ```
</ResponseExample>

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | missing\_parameter | address is missing. |
| 401 | missing\_api\_key | API key missing. |
| 403 | invalid\_api\_key | API key invalid or not enabled for CabalSpy ID. |
| 403 | scope\_not\_allowed | scope=global needs the Enterprise plan. |
| 404 | profile\_not\_found | The wallet is not verified by one of your users. |
| 429 | rate\_limit\_exceeded | Rate limit exceeded. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.