API Reference

List wallets with balances

gethttps://api.circle.com/v1/w3s/developer/wallets/balances

Reference
Playground

Retrieves a list of wallets that match the specified parameters, including native token balances and, if specified, USDC/EURC balances. Balances update automatically with transfers or using the Get token balance for a wallet endpoint for accuracy.

Header parameters

X-Request-Id

string

Developer-provided parameter used to identify this request. Useful when communicating with Circle Support.

Query parameters

blockchain

string

Required

Filter by blockchain.

address

string

Filter by the blockchain address of the wallet.

scaCore

string

Filters results by the SCA version.

walletSetId

uuid

Filter by the wallet set.

refId

string

Filter by the reference identifier.

amount__gte

string

Filters wallets with a balance greater than or equal to the specified amount. If tokenAddress is provided, the filter applies to the specified token; otherwise, it applies to the native token.

tokenAddress

string

Filter by token address.

from

date-time

Queries items created since the specified date-time (inclusive) in ISO 8601 format.

date-time

Queries items created before the specified date-time (inclusive) in ISO 8601 format.

pageBefore

uuid

A collection ID value used for pagination.

It marks the exclusive end of a page. When provided, the collection resource will return the next n items before the id, with n being specified by pageSize.

The items will be returned in the natural order of the collection.

The resource will return the first page if neither pageAfter nor pageBefore are specified.

SHOULD NOT be used in conjunction with pageAfter.

pageAfter

uuid

A collection ID value used for pagination.

It marks the exclusive begin of a page. When provided, the collection resource will return the next n items after the id, with n being specified by pageSize.

The items will be returned in the natural order of the collection.

The resource will return the first page if neither pageAfter nor pageBefore are specified.

SHOULD NOT be used in conjunction with pageBefore.

pageSize

integer

1 to 50

Default is 10

Limits the number of items to be returned.

Some collections have a strict upper bound that will disregard this value. In case the specified value is higher than the allowed limit, the collection limit will be used.

If avoided, the collection will determine the page size itself.

Response

200WalletsWithBalancesResponse

Response Body

object

data

object

Required

Show 1 properties

wallets

array of objects

Required

option 1: EOAWalletWithBalances

Show 14 properties

string

Required

System-generated unique identifier of the resource.

address

string

Required

Blockchain generated unique identifier, associated with wallet (account), smart contract or other blockchain objects.

blockchain

string

Required

The blockchain network that the resource is to be created on or is currently on.

Allowed valuesETHETH-SEPOLIAAVAXAVAX-FUJIMATICMATIC-AMOYSOLSOL-DEVNETARBARB-SEPOLIANEARNEAR-TESTNETEVMEVM-TESTNETUNIUNI-SEPOLIABASEBASE-SEPOLIAOPOP-SEPOLIA

createDate

string

Required

Date and time the resource was created, in ISO-8601 UTC format.

updateDate

string

Required

Date and time the resource was last updated, in ISO-8601 UTC format.

custodyType

string

Required

Describes who controls the digital assets in a wallet: either the end-user or the developer.

Allowed valuesDEVELOPERENDUSER

name

string

Name or description associated with the wallet or walletSet.

refId

string

Reference or description used to identify the object.

state

string

Required

This enum describes the current state of the wallet.

Allowed valuesLIVEFROZEN

userId

string

Unique system generated identifier for the user.

walletSetId

string

Required

System-generated unique identifier of the resource.

initialPublicKey

string

For NEAR blockchains only, the originally assigned public key of a wallet at the time of its creation.

accountType

string

Required

An account can be a Smart Contract Account (SCA) or an Externally Owned Account (EOA). To learn more, see the account types guide.

If an account type is not specified during the creation of a wallet, it defaults to EOA (Externally Owned Account). Note that Solana doesn't support Smart Contract Account (SCA).

Allowed valuesEOA

tokenBalances

array of objects

Required

Lists native token balances and, if specified, USDC/EURC balances for the wallets.

Show 3 properties

amount

string

Required

Token balance for each token in the wallet.

token

object

Required

Show 10 properties

string

Required

System-generated unique identifier of the resource.

name

string

Blockchain name of the specified token.

standard

string

Allowed valuesERC20ERC721ERC1155FungibleFungibleAssetNonFungibleNonFungibleEditionProgrammableNonFungibleProgrammableNonFungibleEdition

blockchain

string

Required

The blockchain network that the resource is to be created on or is currently on.

Allowed valuesETHETH-SEPOLIAAVAXAVAX-FUJIMATICMATIC-AMOYSOLSOL-DEVNETARBARB-SEPOLIANEARNEAR-TESTNETEVMEVM-TESTNETUNIUNI-SEPOLIABASEBASE-SEPOLIAOPOP-SEPOLIA

decimals

integer

Number of decimal places shown in the token amount.

isNative

boolean

Required

Defines if the token is a native token of the specified blockchain. If TRUE, the token is a native token.

symbol

string

Blockchain symbol of the specified token.

tokenAddress

string

Blockchain generated unique identifier, associated with wallet (account), smart contract or other blockchain objects.

updateDate

string

Required

Date and time the resource was last updated, in ISO-8601 UTC format.

createDate

string

Required

Date and time the resource was created, in ISO-8601 UTC format.

updateDate

string

Required

Date and time the resource was last updated, in ISO-8601 UTC format.

option 2: SCAWalletWithBalances

Show 15 properties

string

Required

System-generated unique identifier of the resource.

address

string

Required

Blockchain generated unique identifier, associated with wallet (account), smart contract or other blockchain objects.

blockchain

string

Required

The blockchain network that the resource is to be created on or is currently on.

Allowed valuesETHETH-SEPOLIAAVAXAVAX-FUJIMATICMATIC-AMOYSOLSOL-DEVNETARBARB-SEPOLIANEARNEAR-TESTNETEVMEVM-TESTNETUNIUNI-SEPOLIABASEBASE-SEPOLIAOPOP-SEPOLIA

createDate

string

Required

Date and time the resource was created, in ISO-8601 UTC format.

updateDate

string

Required

Date and time the resource was last updated, in ISO-8601 UTC format.

custodyType

string

Required

Describes who controls the digital assets in a wallet: either the end-user or the developer.

Allowed valuesDEVELOPERENDUSER

name

string

Name or description associated with the wallet or walletSet.

refId

string

Reference or description used to identify the object.

state

string

Required

This enum describes the current state of the wallet.

Allowed valuesLIVEFROZEN

userId

string

Unique system generated identifier for the user.

walletSetId

string

Required

System-generated unique identifier of the resource.

initialPublicKey

string

For NEAR blockchains only, the originally assigned public key of a wallet at the time of its creation.

accountType

string

Required

An account can be a Smart Contract Account (SCA) or an Externally Owned Account (EOA). To learn more, see the account types guide.

If an account type is not specified during the creation of a wallet, it defaults to EOA (Externally Owned Account). Note that Solana doesn't support Smart Contract Account (SCA).

Allowed valuesSCA

scaCore

string

Required

SCAs have different versions, each with unique functionality. SCACore displays the version of the SCA being created. For a list of supported versions, refer to the developer documentation.

Allowed valuescircle_4337_v1circle_6900_singleowner_v1circle_6900_singleowner_v2circle_6900_singleowner_v3

tokenBalances

array of objects

Required

Lists native token balances and, if specified, USDC/EURC balances for the wallets.

Show 3 properties

amount

string

Required

Token balance for each token in the wallet.

token

object

Required

Show 10 properties

string

Required

System-generated unique identifier of the resource.

name

string

Blockchain name of the specified token.

standard

string

Allowed valuesERC20ERC721ERC1155FungibleFungibleAssetNonFungibleNonFungibleEditionProgrammableNonFungibleProgrammableNonFungibleEdition

blockchain

string

Required

The blockchain network that the resource is to be created on or is currently on.

Allowed valuesETHETH-SEPOLIAAVAXAVAX-FUJIMATICMATIC-AMOYSOLSOL-DEVNETARBARB-SEPOLIANEARNEAR-TESTNETEVMEVM-TESTNETUNIUNI-SEPOLIABASEBASE-SEPOLIAOPOP-SEPOLIA

decimals

integer

Number of decimal places shown in the token amount.

isNative

boolean

Required

Defines if the token is a native token of the specified blockchain. If TRUE, the token is a native token.

symbol

string

Blockchain symbol of the specified token.

tokenAddress

string

Blockchain generated unique identifier, associated with wallet (account), smart contract or other blockchain objects.

updateDate

string

Required

Date and time the resource was last updated, in ISO-8601 UTC format.

createDate

string

Required

Date and time the resource was created, in ISO-8601 UTC format.

updateDate

string

Required

Date and time the resource was last updated, in ISO-8601 UTC format.

401NotAuthorizedResponse

RequestChoose a language

ResponseChoose an example

1{
2  "data": {
3    "wallets": [
4      {
5        "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
6        "address": "0xca9142d0b9804ef5e239d3bc1c7aa0d1c74e7350",
7        "blockchain": "MATIC-AMOY",
8        "createDate": "2023-01-01T12:04:05Z",
9        "updateDate": "2023-01-01T12:04:05Z",
10        "custodyType": "DEVELOPER",
11        "name": "",
12        "refId": "custom_ref_id",
13        "state": "LIVE",
14        "userId": "ext_user_id_1",
15        "walletSetId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
16        "initialPublicKey": "3eQoJ3ex6uWX3R8F1THF6Y6oBQwPYpF1X9HBM1gjqw7w",
17        "accountType": "EOA",
18        "tokenBalances": [
19          {
20            "amount": "6.62607015",
21            "token": {
22              "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
23              "name": "",
24              "standard": "ERC20",
25              "blockchain": "MATIC-AMOY",
26              "decimals": 0,
27              "isNative": false,
28              "symbol": "",
29              "tokenAddress": "0xca9142d0b9804ef5e239d3bc1c7aa0d1c74e7350",
30              "updateDate": "2023-01-01T12:04:05Z",
31              "createDate": "2023-01-01T12:04:05Z"
32            },
33            "updateDate": "2023-01-01T12:04:05Z"
34          }
35        ]
36      }
37    ]
38  }
39}

Did this page help you?

Developer Terms Service Terms Privacy Policy Acceptable Use Your Privacy Choices

Cookie Policy