Get Wallet Balance

Get the balance of a wallet for a given chain and currency

API scope required: wallets:balance.read

GET /2025-06-09/wallets/{walletLocator}/balances

Try it

Get Wallet Balance

cURL

curl --request GET \
  --url https://staging.crossmint.com/api/2025-06-09/wallets/{walletLocator}/balances \
  --header 'X-API-KEY: <x-api-key>'

200

[
  {
    "symbol": "ETH",
    "name": "Ethereum",
    "decimals": 18,
    "amount": "18.8343253454",
    "rawAmount": "18834161225104097789",
    "chains": {
      "base": {
        "contractAddress": "0x123",
        "locator": "base:0x123",
        "amount": "18.833423432423",
        "rawAmount": "18834161225104097789"
      },
      "solana": {
        "mintHash": "123123",
        "locator": "solana:132",
        "amount": "0.000000000000000",
        "rawAmount": "00000000000000000"
      }
    }
  }
]

Example Request

This example uses placeholder values. Modify the call with the wallet locator, tokens, and chains you would like to use.

cURL

curl --request GET \
  --url 'https://staging.crossmint.com/api/2025-06-09/wallets/email:[e-mail]:evm/balances?tokens=usdc,eth,pol&chains=base-sepolia,polygon-amoy' \
  --header 'X-API-KEY: <x-api-key>'

Example Response

The response returns an array of token objects, each containing balance information across the specified chains:

[
    {
        "symbol": "ETH",
        "name": "Ethereum",
        "decimals": 18,
        "amount": "1.5",
        "rawAmount": "1500000000000000000",
        "chains": {
            "base-sepolia": {
                "locator": "base-sepolia:eth",
                "amount": "1.0",
                "rawAmount": "1000000000000000000"
            },
            "polygon-amoy": {
                "locator": "polygon-amoy:eth",
                "amount": "0.5",
                "rawAmount": "500000000000000000"
            }
        }
    },
    {
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "amount": "100.0",
        "rawAmount": "100000000",
        "chains": {
            "base-sepolia": {
                "locator": "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                "amount": "50.0",
                "rawAmount": "50000000",
                "contractAddress": "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
            },
            "polygon-amoy": {
                "locator": "polygon-amoy:0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582",
                "amount": "50.0",
                "rawAmount": "50000000",
                "contractAddress": "0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582"
            }
        }
    },
    {
        "symbol": "SOL",
        "decimals": 9,
        "amount": "2.5",
        "rawAmount": "2500000000",
        "chains": {
            "solana": {
                "locator": "solana:sol",
                "amount": "2.5",
                "rawAmount": "2500000000"
            }
        }
    },
    {
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "amount": "75.0",
        "rawAmount": "75000000",
        "chains": {
            "solana": {
                "locator": "solana:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
                "amount": "75.0",
                "rawAmount": "75000000",
                "mintHash": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
            }
        }
    }
]

Headers

X-API-KEY · string · required

API key required for authentication

Path Parameters

walletLocator · string · required

A wallet locator can be of the format:

• <walletAddress>
• email:<email>:<chainType>[:<walletType>][:alias:<alias>] (walletType defaults to 'smart')
• userId:<userId>:<chainType>[:<walletType>][:alias:<alias>] (white label user example)
• phoneNumber:<phoneNumber>:<chainType>[:<walletType>][:alias:<alias>]
• twitter:<handle>:<chainType>[:<walletType>][:alias:<alias>]
• x:<handle>:<chainType>[:<walletType>][:alias:<alias>]
• me:<chainType>[:<walletType>][:alias:<alias>] (Use when calling from the client side with a client API key)
• chainType[:<walletType>]:alias:<alias>

Query Parameters

chains · string

The blockchain(s) to query. Comma-separated list of chains

tokens · string · required

The tokens to query. Comma-separated list of either tokens or token locator strings

Response

200

application/json

Returns the balance of the wallet for the given chain and currency

decimals · number · required

The number of decimals of the token

Example:

18

amount · string · required

The amount of the token after placing the decimal point

Example:

"18.8343253454"

rawAmount · string · required

The raw amount of the token

Example:

"18834161225104097789"

chains · object · required

Balance information per chain

Show child attributes

chains. {key} · object

Balance information per chain

Option 1

Show child attributes

chains.{key}. locator · string · required

Either a token string (e.g., 'eth', 'sol') or a token locator string (e.g., 'ethereum:0x123', 'solana:sol')

Example:

"ethereum:0x123"

chains.{key}. amount · string · required

The amount of the token after placing the decimal point

Example:

"18.8343253454"

chains.{key}. rawAmount · string · required

The raw amount of the token

Example:

"18834161225104097789"

chains.{key}. contractAddress · string

The contract address of the token on the EVM chain. Not present for native tokens.

Example:

"0x123"

Example:

{
  "locator": "base:0x123",
  "amount": "18.833423432423",
  "rawAmount": "18834161225104097789",
  "contractAddress": "0x123"
}

Example:

{
  "base": {
    "contractAddress": "0x123",
    "locator": "base:0x123",
    "amount": "18.833423432423",
    "rawAmount": "18834161225104097789"
  },
  "solana": {
    "mintHash": "123123",
    "locator": "solana:132",
    "amount": "0",
    "rawAmount": "00000000000000000"
  }
}

symbol · string

name · string

The name of the token

Example:

"USDC Token"

Example:

[
  {
    "symbol": "ETH",
    "name": "Ethereum",
    "decimals": 18,
    "amount": "18.8343253454",
    "rawAmount": "18834161225104097789",
    "chains": {
      "base": {
        "contractAddress": "0x123",
        "locator": "base:0x123",
        "amount": "18.833423432423",
        "rawAmount": "18834161225104097789"
      },
      "solana": {
        "mintHash": "123123",
        "locator": "solana:132",
        "amount": "0.000000000000000",
        "rawAmount": "00000000000000000"
      }
    }
  }
]