Get Wallet Balance

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

import requests

url = "https://staging.crossmint.com/api/2025-06-09/wallets/{walletLocator}/balances"

headers = {"X-API-KEY": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};

fetch('https://staging.crossmint.com/api/2025-06-09/wallets/{walletLocator}/balances', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://staging.crossmint.com/api/2025-06-09/wallets/{walletLocator}/balances",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://staging.crossmint.com/api/2025-06-09/wallets/{walletLocator}/balances"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-KEY", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://staging.crossmint.com/api/2025-06-09/wallets/{walletLocator}/balances")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<api-key>'

response = http.request(request)
puts response.read_body

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

{
  "error": true,
  "message": "<error message>",
  "code": "DEVICE_SIGNER_NOT_SUPPORTED"
}

GET

2025-06-09

wallets

{walletLocator}

balances

Get Wallet Balance

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

import requests

url = "https://staging.crossmint.com/api/2025-06-09/wallets/{walletLocator}/balances"

headers = {"X-API-KEY": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};

fetch('https://staging.crossmint.com/api/2025-06-09/wallets/{walletLocator}/balances', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://staging.crossmint.com/api/2025-06-09/wallets/{walletLocator}/balances",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://staging.crossmint.com/api/2025-06-09/wallets/{walletLocator}/balances"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-KEY", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://staging.crossmint.com/api/2025-06-09/wallets/{walletLocator}/balances")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<api-key>'

response = http.request(request)
puts response.read_body

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

{
  "error": true,
  "message": "<error message>",
  "code": "DEVICE_SIGNER_NOT_SUPPORTED"
}

This is an alpha API and subject to change.

Example Request

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

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: <x-api-key>'

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": "<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);
}

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": "<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:

[
    {
        "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"
            }
        }
    }
]

Authorizations

X-API-KEY

string

header

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

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

amount

string

required

The amount of the token after placing the decimal point

Example:

"18.8343253454"

chains

object

required

Balance information per chain

Show child attributes

Example:

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

decimals

number

required

The number of decimals of the token

Example:

18

rawAmount

string

required

The raw amount of the token

Example:

"18834161225104097789"

name

string

The name of the token

Example:

"USDC Token"

symbol

string

Example:

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

Introduction

Quickstarts ⚡

Concepts

Guides

API Reference

Get Wallet Balance

Example Request

Example Response

Authorizations

Path Parameters

Query Parameters

Response

​Example Request

​Example Response

Authorizations

Path Parameters

Query Parameters

Response

Example Request

Example Response