Wallets

Wallets are addresses registered to customers, in the API key's environment. A wallet in the registry is hosted by you; counterparties' discovery and incoming transfers match against it. A wallet holds no personal data, so every role sees it in full.

Endpoints

Method	Endpoint	Scope	Description
GET	/api/v2/wallets	wallets:read	List wallets
POST	/api/v2/wallets	wallets:write	Register a wallet
GET	/api/v2/wallets/:id	wallets:read	Get a wallet
PATCH	/api/v2/wallets/:id	wallets:write	Change a wallet's label
DELETE	/api/v2/wallets/:id	wallets:write	Remove a wallet
POST	/api/v2/wallets/verify	wallets:verify	Check whether an address is a registered wallet

A wallet of the other environment is not found: 404 WALLET_NOT_FOUND.

The Wallet

Every wallet answer, single or listed, has these fields, and no others:

{
  "id": "wallet_id",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "network": "ethereum",
  "customerId": "customer_id",
  "label": "Main wallet",
  "verified": false,
  "verifiedAt": null,
  "environment": "live",
  "createdAt": "2026-10-09T12:00:00.000Z",
  "updatedAt": "2026-10-09T12:00:00.000Z"
}

Field	Description
label	Your label, or null.
verified	Whether the customer's ownership is proven: true while at least one of the wallet's ownership proofs is valid. Proofs are managed in the dashboard.
verifiedAt	When ownership was last proven, or null.
environment	test or live: the key's.

List Wallets

curl "$COVALENT_URL/api/v2/wallets?customerId=customer_id&limit=50" \
  -H "x-api-key: $COVALENT_API_KEY"

Query parameters:

Parameter	Description
network	One network's wallets.
verified	true or false.
customerId	One customer's wallets.
search	Part of the address, the label or the customer ID.
limit	Items per page, 1 to 100, default 50.
cursor	meta.cursor of the previous page.

The answer is a list of wallets, newest first, with meta.cursor, hasMore, total and limit. An unknown parameter, or a value a filter cannot take (verified other than true or false, a malformed customerId, a limit out of range, text longer than 200 characters), is 400 INVALID_QUERY. A network that no wallet uses matches nothing.

Register Wallet

curl -X POST "$COVALENT_URL/api/v2/wallets" \
  -H "x-api-key: $COVALENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "network": "ethereum",
    "customerId": "customer_id",
    "label": "Main wallet"
  }'

Field	Required	Description
address	Yes	The address, in the network's format.
network	Yes	A supported network, by name.
customerId	Yes	A customer of the key's environment that is not deactivated.
label	No	Text, or null.

The answer is 201 with the wallet. Registering an address its customer already has updates that wallet's network and label.

Supported networks: bitcoin, ethereum, polygon, bsc, solana, tron, avalanche, arbitrum, optimism, base, litecoin, ripple, stellar, algorand, dogecoin, cardano, cosmos, near, polkadot, fantom, bitcoin-cash. An alias such as eth is refused.

Status	Code	When
400	MISSING_FIELDS	address, network or customerId is missing.
400	INVALID_FIELDS	customerId is not a string, or label is neither a string nor null.
404	CUSTOMER_NOT_FOUND	No such customer in the key's environment. A customer of the other environment is not found either.
400	CUSTOMER_DEACTIVATED	The customer is deactivated.
400	INVALID_ADDRESS	The address is not in the network's format.
400	UNSUPPORTED_NETWORK	The network is not supported.
409	WALLET_ADDRESS_TAKEN	The address is registered to another customer of the environment.

{
  "error": "Wallet address already registered to a different customer",
  "code": "WALLET_ADDRESS_TAKEN",
  "meta": {
    "apiVersion": 2,
    "timestamp": "2026-10-09T12:00:00.000Z"
  }
}

Get Wallet

curl "$COVALENT_URL/api/v2/wallets/wallet_id" \
  -H "x-api-key: $COVALENT_API_KEY"

The answer is the wallet.

Update Wallet

curl -X PATCH "$COVALENT_URL/api/v2/wallets/wallet_id" \
  -H "x-api-key: $COVALENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Treasury wallet"
  }'

Only label changes: a string sets it, null clears it. A body without label changes nothing and answers the wallet as it is. Whether a wallet is verified follows its ownership proofs, never a request.

The answer is the wallet. A body that is not a JSON object is 400 VALIDATION_ERROR; a label that is neither a string nor null is 400 INVALID_FIELDS.

Delete Wallet

curl -X DELETE "$COVALENT_URL/api/v2/wallets/wallet_id" \
  -H "x-api-key: $COVALENT_API_KEY"

The wallet is removed with its ownership proofs:

{
  "data": {
    "id": "wallet_id",
    "deleted": true
  },
  "meta": {
    "apiVersion": 2,
    "timestamp": "2026-10-09T12:00:00.000Z"
  }
}

Verify Wallet

Checks whether an address is a wallet the registry holds in the key's environment. You make your own decision from the answer; nothing is rejected for you.

curl -X POST "$COVALENT_URL/api/v2/wallets/verify" \
  -H "x-api-key: $COVALENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "network": "ethereum"
  }'

address is required; network is optional.

{
  "data": {
    "isRegistered": true,
    "isVerified": true,
    "walletType": "hosted",
    "customerId": "customer_id"
  },
  "meta": {
    "apiVersion": 2,
    "timestamp": "2026-10-09T12:00:00.000Z"
  }
}

Field	Description
isRegistered	Whether the registry holds the address.
isVerified	Whether the wallet's ownership is proven. false when the wallet is registered for another network than the one asked about.
walletType	hosted for a registered wallet (held by you, for EU TFR Article 14), unknown otherwise.
customerId	The wallet's customer. Absent for an address the registry does not hold.

A request without address is 400 MISSING_FIELDS; an address or network that is not a string is 400 INVALID_FIELDS.