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

# Add and remove wallets

> POST /v1/platform-users/wallets/add and /wallets/delete: add a platform user's existing wallets without payment verification, or remove one.

Add wallets your user already has, from Privy, Dynamic or any other provider, without a payment. They are unverified and count straight away unless your instance sets `wallet_trust` to `verified_only`, see [Unverified and verified wallets](https://docs.cabalspy.xyz/cabalspy-id/white-label.md#unverified-and-verified-wallets). To prove ownership with a payment, use [Verify a wallet](https://docs.cabalspy.xyz/cabalspy-id/platform-users-verification.md).

## Add wallets

`POST /v1/platform-users/wallets/add`

Adding a wallet that already exists only adds the chains that are new. A user can hold up to 5 Solana and 5 EVM wallets.

### Body

**external\_id** `string` *required*

Your id of the user. Alternatively pass csid\_id.

**wallets** `array` *required*

1 to 10 wallets, objects with address, chains and source, or plain addresses. See [Create or update a user](https://docs.cabalspy.xyz/cabalspy-id/platform-users-create.md#body). For a single wallet you can instead pass `address`, `chains` and `source` at the top level.

### Usage Example

```bash cURL theme={null}
curl -X POST "https://api-id.cabalspy.xyz/v1/platform-users/wallets/add" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user_8412",
    "wallets": [{"address": "0x4b1e9c0d2a7f3e5b8c6d1a9f0e2b7c4d5a6e8f01", "chains": ["base", "eth"], "source": "dynamic"}]
  }'
```

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

r = requests.post("https://api-id.cabalspy.xyz/v1/platform-users/wallets/add",
                  json={"external_id": "user_8412", "address": "0x4b1e9c0d2a7f3e5b8c6d1a9f0e2b7c4d5a6e8f01"},
                  headers={"Authorization": "Bearer YOUR_KEY"})
print(r.status_code, r.json()["data"]["wallets_added"])
```

```javascript JavaScript theme={null}
const res = await fetch("https://api-id.cabalspy.xyz/v1/platform-users/wallets/add", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    external_id: "user_8412",
    wallets: ["0x4b1e9c0d2a7f3e5b8c6d1a9f0e2b7c4d5a6e8f01"],
  }),
});
const { data } = await res.json();
console.log(res.status, data.wallets_added, data.wallets.length);
```

### Response

**201** when something was added, **200** when every wallet and chain already existed.

**data** `object`

**data**

**external\_id** `string`

Your id of the user.

**wallets\_added** `array`

Wallets and chains that are new: address, family, chains and source.

**wallets** `array`

All the user's wallets with their status, as in the [user object](https://docs.cabalspy.xyz/cabalspy-id/platform-users-get.md#response).

```json Response theme={null}
{
  "success": true,
  "data": {
    "external_id": "user_8412",
    "wallets_added": [
      { "address": "0x4b1e9c0d2a7f3e5b8c6d1a9f0e2b7c4d5a6e8f01", "family": "evm", "chains": ["base", "eth"], "source": "dynamic" }
    ],
    "wallets": [
      {
        "address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
        "family": "solana",
        "chains": ["solana"],
        "verified": false,
        "verified_chains": [],
        "status": "active",
        "counts": true,
        "source": "privy",
        "verified_at": null,
        "added_at": "2026-10-24T09:12:40Z"
      },
      {
        "address": "0x4b1e9c0d2a7f3e5b8c6d1a9f0e2b7c4d5a6e8f01",
        "family": "evm",
        "chains": ["base", "eth"],
        "verified": false,
        "verified_chains": [],
        "status": "active",
        "counts": true,
        "source": "dynamic",
        "verified_at": null,
        "added_at": "2026-10-26T08:04:11Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_5162c7cf7f87",
    "cached": false,
    "cache_age_seconds": 0,
    "version": "v1",
    "timestamp": "2026-10-26T08:04:11Z"
  }
}
```

Each new wallet triggers the `wallet.added` [webhook](https://docs.cabalspy.xyz/cabalspy-id/webhooks.md#white-label-events).

## Remove a wallet

`POST /v1/platform-users/wallets/delete`

Removes one wallet, verified or not, from the user. Every user needs at least one wallet, so the last one cannot be removed: add another first, or [delete the user](https://docs.cabalspy.xyz/cabalspy-id/platform-users-delete.md).

**external\_id** `string` *required*

Your id of the user. Alternatively pass csid\_id.

**address** `string` *required*

The wallet to remove.

```bash cURL theme={null}
curl -X POST "https://api-id.cabalspy.xyz/v1/platform-users/wallets/delete" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "user_8412", "address": "0x4b1e9c0d2a7f3e5b8c6d1a9f0e2b7c4d5a6e8f01"}'
```

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

r = requests.post("https://api-id.cabalspy.xyz/v1/platform-users/wallets/delete",
                  json={"external_id": "user_8412", "address": "0x4b1e9c0d2a7f3e5b8c6d1a9f0e2b7c4d5a6e8f01"},
                  headers={"Authorization": "Bearer YOUR_KEY"})
print(r.json()["data"])
```

```javascript JavaScript theme={null}
const res = await fetch("https://api-id.cabalspy.xyz/v1/platform-users/wallets/delete", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ external_id: "user_8412", address: "0x4b1e9c0d2a7f3e5b8c6d1a9f0e2b7c4d5a6e8f01" }),
});
console.log((await res.json()).data.removed);
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "external_id": "user_8412",
    "address": "0x4b1e9c0d2a7f3e5b8c6d1a9f0e2b7c4d5a6e8f01",
    "removed": true
  },
  "meta": { "request_id": "req_5162c7cf7f87", "cached": false, "cache_age_seconds": 0, "version": "v1", "timestamp": "2026-10-26T08:10:02Z" }
}
```

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | missing\_parameter | external\_id or address missing. |
| 400 | invalid\_parameter | A wallet's chains or source invalid, or more than 10 wallets. |
| 400 | wallet\_required | Add: no wallets passed. |
| 400 | invalid\_address | Not a valid Solana or EVM address. |
| 401 | missing\_api\_key | API key missing. |
| 403 | invalid\_api\_key | API key invalid or not enabled for CabalSpy ID. |
| 404 | platform\_user\_not\_found | No user with this id in your instance. |
| 404 | wallet\_not\_found | Remove: the user has no such wallet. |
| 409 | account\_claimed | The person claimed the account and manages it themselves. |
| 409 | too\_many\_wallets | The user would have more than 5 Solana or 5 EVM wallets. |
| 409 | last\_wallet | Remove: this is the user's only wallet. |
| 429 | rate\_limit\_exceeded | Rate limit exceeded. |

See [Errors](https://docs.cabalspy.xyz/cabalspy-id/errors.md) for the full list.


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