> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crossmint.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Wallet Balance
> Get the balance of a wallet for a given chain and currency
**API scope required**: `wallets:balance.read`
## Example Request
This example uses placeholder values. Modify the call with the wallet locator, tokens, and chains you would like to use.
```bash cURL theme={null}
curl --request GET \
--url 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/balances?tokens=usdc,eth,pol&chains=base-sepolia,polygon-amoy' \
--header 'X-API-KEY: '
```
```js Node.js theme={null}
const url =
"https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/balances?tokens=usdc,eth,pol&chains=base-sepolia,polygon-amoy";
const options = { method: "GET", headers: { "X-API-KEY": "" }, body: undefined };
try {
const response = await fetch(url, options);
const data = await response.json();
// Process each token's balance across chains
data.forEach((token) => {
console.log(`${token.symbol}${token.name ? ` (${token.name})` : ""}:`);
console.log(` Total amount: ${token.amount} (${token.rawAmount} raw)`);
console.log(` Decimals: ${token.decimals}`);
// Access balance data for each chain
Object.entries(token.chains).forEach(([chainName, chainBalance]) => {
console.log(` ${chainName}: ${chainBalance.amount}`);
console.log(` Locator: ${chainBalance.locator}`);
if (chainBalance.contractAddress) {
console.log(` Contract: ${chainBalance.contractAddress}`);
} else if (chainBalance.mintHash) {
console.log(` Mint Hash: ${chainBalance.mintHash}`);
} else if (chainBalance.contractId) {
console.log(` Contract ID: ${chainBalance.contractId}`);
}
});
console.log();
});
} catch (error) {
console.error(error);
}
```
```python Python theme={null}
import requests
url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/balances"
querystring = { "tokens": "usdc,eth,pol", "chains": "base-sepolia,polygon-amoy" }
headers = { "X-API-KEY": "" }
response = requests.get(url, params=querystring, headers=headers)
data = response.json()
# Process each token's balance across chains
for token in data:
name_part = f" ({token['name']})" if token.get('name') else ""
print(f"{token['symbol']}{name_part}:")
print(f" Total amount: {token['amount']} ({token['rawAmount']} raw)")
print(f" Decimals: {token['decimals']}")
# Access balance data for each chain
for chain_name, chain_balance in token['chains'].items():
print(f" {chain_name}: {chain_balance['amount']}")
print(f" Locator: {chain_balance['locator']}")
if 'contractAddress' in chain_balance:
print(f" Contract: {chain_balance['contractAddress']}")
elif 'mintHash' in chain_balance:
print(f" Mint Hash: {chain_balance['mintHash']}")
elif 'contractId' in chain_balance:
print(f" Contract ID: {chain_balance['contractId']}")
print()
```
## Example Response
The response returns an array of token objects, each containing balance information across the specified chains:
```json theme={null}
[
{
"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"
}
}
}
]
```
## OpenAPI
````yaml get /2025-06-09/wallets/{walletLocator}/balances
openapi: 3.0.0
info:
title: Crossmint Wallets API
description: Crossmint Wallets API
version: 1.0.0
contact:
name: Crossmint Support
url: https://www.crossmint.com
email: support@crossmint.com
servers:
- url: https://staging.crossmint.com/api
description: Staging environment (testnets)
- url: https://www.crossmint.com/api
description: Production environment (mainnets)
security: []
tags: []
paths:
/2025-06-09/wallets/{walletLocator}/balances:
get:
summary: Get Wallet Balance
description: |-
Get the balance of a wallet for a given chain and currency
**API scope required**: `wallets:balance.read`
operationId: BalanceV20250609Controller-getBalanceForLocator-2
parameters:
- name: X-API-KEY
in: header
description: API key required for authentication
required: true
schema:
type: string
- name: walletLocator
required: true
in: path
description: >-
A wallet locator can be of the format:
- ``
- `email::[:][:alias:]`
(walletType defaults to 'smart')
- `userId::[:][:alias:]`
(white label user example)
-
`phoneNumber::[:][:alias:]`
- `twitter::[:][:alias:]`
- `x::[:][:alias:]`
- `me:[:][:alias:]` (Use when calling
from the client side with a client API key)
- `chainType[:]:alias:`
example:
- '0x1234567890123456789012345678901234567890'
- email:user@example.com:evm:smart
- email:user@example.com:evm
- email:user@example.com:evm:smart:alias:myWallet
- userId:507f1f77bcf86cd799439011:solana:mpc
- userId:did:example:cm4lr5piw0h6t1bjho0onryql:evm:smart
- userId:507f1f77bcf86cd799439011:evm:alias:primary
- phoneNumber:+12125551234:evm:smart
- phoneNumber:+12125551234:evm:smart:alias:mobile
- twitter:johndoe:evm:smart
- x:@johndoe:evm:smart:alias:xWallet
- me:evm:smart
- me:evm:smart:alias:personal
- evm:alias:myAlias
schema:
type: string
- name: chains
required: false
in: query
description: The blockchain(s) to query. Comma-separated list of chains
example: ethereum,polygon
schema:
type: string
- name: tokens
required: true
in: query
description: >-
The tokens to query. Comma-separated list of either tokens or token
locator strings
example: eth,base:0x123,solana:sol
schema:
type: string
responses:
'200':
description: Returns the balance of the wallet for the given chain and currency
content:
application/json:
schema:
$ref: '#/components/schemas/WalletBalanceV20250609ResponseDTO'
'400':
description: >-
Returns an error (400) if the wallet locator is invalid or if the
address type is not supported
content:
application/json:
schema:
$ref: '#/components/schemas/WalletV1Alpha2ErrorDTO'
components:
schemas:
WalletBalanceV20250609ResponseDTO:
type: array
items:
type: object
properties:
symbol:
type: string
name:
type: string
description: The name of the token
example: USDC Token
decimals:
type: number
description: The number of decimals of the token
example: 18
amount:
type: string
description: The amount of the token after placing the decimal point
example: '18.8343253454'
rawAmount:
type: string
description: The raw amount of the token
example: '18834161225104097789'
chains:
type: object
additionalProperties:
oneOf:
- type: object
properties:
locator:
type: string
description: >-
Either a token string (e.g., 'eth', 'sol') or a token
locator string (e.g., 'ethereum:0x123', 'solana:sol')
example: ethereum:0x123
amount:
type: string
description: The amount of the token after placing the decimal point
example: '18.8343253454'
rawAmount:
type: string
description: The raw amount of the token
example: '18834161225104097789'
contractAddress:
type: string
description: >-
The contract address of the token on the EVM chain. Not
present for native tokens.
example: '0x123'
required:
- locator
- amount
- rawAmount
additionalProperties: false
description: Balance information per chain
example:
locator: base:0x123
amount: '18.833423432423'
rawAmount: '18834161225104097789'
contractAddress: '0x123'
- type: object
properties:
locator:
type: string
description: >-
Either a token string (e.g., 'eth', 'sol') or a token
locator string (e.g., 'ethereum:0x123', 'solana:sol')
example: ethereum:0x123
amount:
type: string
description: The amount of the token after placing the decimal point
example: '18.8343253454'
rawAmount:
type: string
description: The raw amount of the token
example: '18834161225104097789'
mintHash:
type: string
description: >-
The mint hash of the token on Solana. Not present for
native SOL.
example: '123123'
required:
- locator
- amount
- rawAmount
additionalProperties: false
description: Balance information for chain
example:
locator: solana:31123
amount: '18.833423432423'
rawAmount: '18834161225104097789'
mintHash: '123123'
- type: object
properties:
locator:
type: string
description: >-
Either a token string (e.g., 'eth', 'sol') or a token
locator string (e.g., 'ethereum:0x123', 'solana:sol')
example: ethereum:0x123
amount:
type: string
description: The amount of the token after placing the decimal point
example: '18.8343253454'
rawAmount:
type: string
description: The raw amount of the token
example: '18834161225104097789'
contractId:
type: string
description: >-
The contract ID of the token on Stellar. Not present for
native XLM.
example: CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75
required:
- locator
- amount
- rawAmount
additionalProperties: false
description: Balance information for Stellar chain
example:
locator: stellar:xlm
amount: '100.5000000'
rawAmount: '1005000000'
contractId: CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA
description: Balance information per chain
example:
base:
contractAddress: '0x123'
locator: base:0x123
amount: '18.833423432423'
rawAmount: '18834161225104097789'
solana:
mintHash: '123123'
locator: solana:132
amount: '0'
rawAmount: '00000000000000000'
required:
- decimals
- amount
- rawAmount
- chains
description: Array of wallet balances per 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'
WalletV1Alpha2ErrorDTO:
type: object
properties:
error:
type: boolean
enum:
- true
message:
type: string
description: Error message
example:
required:
- error
- message
description: Wallet error
````