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

**address** `string` *required*

The wallet address to look up.

**scope** `string` (default: instance)

`global` searches every CabalSpy ID user. Enterprise plan only.

**instance** `string`

Your Instance ID. Only needed when your account has several instances.

**api\_key** `string` *required*

Your API key. Alternatively pass it as an Authorization Bearer header.

## Usage Example

```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);
```

## Response

**success** `boolean`

True on success.

**data** `object`

**data**

**address** `string`

The address you asked for.

**verified** `boolean`

Always true on success.

**wallet** `object`

**wallet**

**address** `string`

Wallet address as verified.

**family** `string`

solana or evm.

**chains** `array`

Chains the wallet is verified on.

**verified\_at** `string`

When the wallet was verified.

**owner** `object`

The owner's profile, the same fields as [Profile](https://docs.cabalspy.xyz/cabalspy-id/profile.md) 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.

```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"
  }
}
```

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | missing\_parameter | address is missing. |
| 401 | missing\_api\_key | API key missing. |
| 403 | invalid\_api\_key | API key invalid. |
| 403 | product\_not\_enabled | The key is not enabled for the CabalSpy ID API (API keys page, Works with). |
| 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.