Get Address Balance

curl --request GET \
  --url https://secureapi.tender.cash/v1/api/wallet/balance/{address} \
  --header 'authorization: <api-key>' \
  --header 'x-access-id: <x-access-id>' \
  --header 'x-request-id: <x-request-id>' \
  --header 'x-timestamp: <x-timestamp>'

const options = {
  method: 'GET',
  headers: {
    authorization: '<api-key>',
    'x-timestamp': '<x-timestamp>',
    'x-request-id': '<x-request-id>',
    'x-access-id': '<x-access-id>'
  }
};

fetch('https://secureapi.tender.cash/v1/api/wallet/balance/{address}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://secureapi.tender.cash/v1/api/wallet/balance/{address}"

headers = {
    "authorization": "<api-key>",
    "x-timestamp": "<x-timestamp>",
    "x-request-id": "<x-request-id>",
    "x-access-id": "<x-access-id>"
}

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

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://secureapi.tender.cash/v1/api/wallet/balance/{address}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "authorization: <api-key>",
    "x-access-id: <x-access-id>",
    "x-request-id: <x-request-id>",
    "x-timestamp: <x-timestamp>"
  ],
]);

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

curl_close($curl);

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

{
  "status": "success",
  "message": "success",
  "data": {
    "balances": {
      "native": 0.0021,
      "USDT": 8,
      "USDC": 0
    }
  }
}

{
  "status": "error",
  "message": "chain query param is required",
  "data": null
}

{
  "status": "error",
  "message": "INVALID_REQUEST_SIGNATURE",
  "data": null
}

{
  "status": "error",
  "message": "Too many requests. Max 30 per 60s.",
  "data": null
}

{
  "status": "error",
  "message": "Wallet service is temporarily unavailable. Please try again.",
  "data": null
}

GET

api

wallet

balance

{address}

Get Address Balance

curl --request GET \
  --url https://secureapi.tender.cash/v1/api/wallet/balance/{address} \
  --header 'authorization: <api-key>' \
  --header 'x-access-id: <x-access-id>' \
  --header 'x-request-id: <x-request-id>' \
  --header 'x-timestamp: <x-timestamp>'

const options = {
  method: 'GET',
  headers: {
    authorization: '<api-key>',
    'x-timestamp': '<x-timestamp>',
    'x-request-id': '<x-request-id>',
    'x-access-id': '<x-access-id>'
  }
};

fetch('https://secureapi.tender.cash/v1/api/wallet/balance/{address}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://secureapi.tender.cash/v1/api/wallet/balance/{address}"

headers = {
    "authorization": "<api-key>",
    "x-timestamp": "<x-timestamp>",
    "x-request-id": "<x-request-id>",
    "x-access-id": "<x-access-id>"
}

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

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://secureapi.tender.cash/v1/api/wallet/balance/{address}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "authorization: <api-key>",
    "x-access-id: <x-access-id>",
    "x-request-id: <x-request-id>",
    "x-timestamp: <x-timestamp>"
  ],
]);

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

curl_close($curl);

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

{
  "status": "success",
  "message": "success",
  "data": {
    "balances": {
      "native": 0.0021,
      "USDT": 8,
      "USDC": 0
    }
  }
}

{
  "status": "error",
  "message": "chain query param is required",
  "data": null
}

{
  "status": "error",
  "message": "INVALID_REQUEST_SIGNATURE",
  "data": null
}

{
  "status": "error",
  "message": "Too many requests. Max 30 per 60s.",
  "data": null
}

{
  "status": "error",
  "message": "Wallet service is temporarily unavailable. Please try again.",
  "data": null
}

Auth method: Signed (HMAC) — this endpoint requires the full set of signed headers: x-access-id, x-request-id, x-timestamp, and an HMAC-SHA256 authorization signature. See Authentication.

Returns the on-chain balances of an address. Without currency, you get every balance Tender tracks for the address. With currency, you get a single number. Balances are cached for 180 seconds, so a deposit or transfer can take up to three minutes to show here. Use the deposit and transfer webhooks for real-time updates.

Example

// All balances
const all = await fetch(`${BASE}/wallet/balance/0x4f2a9b...?chain=ethereum`, {
  headers: makeHeaders(),
});
const { data } = await all.json();
// data.balances → { native: 0.0021, USDT: 8, USDC: 0 }

// One currency
const one = await fetch(`${BASE}/wallet/balance/0x4f2a9b...?chain=ethereum&currency=usdt`, {
  headers: makeHeaders(),
});
const { data: single } = await one.json();
// single.balance → 8

res = requests.get(
    f"{BASE}/wallet/balance/0x4f2a9b...",
    params={"chain": "ethereum", "currency": "usdt"},
    headers=make_headers(),
)
balance = res.json()["data"]["balance"]
# balance → 8

Headers

string

required

Base64-encoded HMAC-SHA256 signature of {"timeStamp":"<x-timestamp>","requestId":"<x-request-id>","accessId":"<x-access-id>"}, signed with your access secret. The request body is not part of the signature.Example: "pV3n0o8kq0lK2mJ8bZ1yq3Yt6hR0cXK9u4mVJ2l9sE0="

string

required

ISO 8601 timestamp; must be within 5 minutes of server timeExample: "2026-10-15T09:45:53.000Z"

string

required

A unique UUID v4 per requestExample: "550e8400-e29b-41d4-a716-446655440000"

string

required

Your API access IDExample: "your-access-id-here"

Path Parameters

string

required

The blockchain address to query.Example: "0x4f2a9b..."

Query Parameters

string

required

Chain the address is on: ethereum, tron or bitcoin.Example: "ethereum"

string

Optional currency symbol, matched case-insensitively (for example USDT, usdc, ETH). It must be supported on chain. Omit it to get all balances.Example: "USDT"

Response

string

required

Example: "success"

string

required

Example: "success"

object

required

The shape depends on whether you sent currency.

Show data without currency

object

Balances in human-readable units, keyed by asset.

Show balances properties

number

Balance of the chain’s native coin (ETH, TRX or BTC).Example: 0.0021

number

USDT balance. Present on ethereum and tron only.Example: 8

number

USDC balance. Present on ethereum and tron only.Example: 0

Show data with currency

number

Balance of the requested currency in human-readable units. 0 if the balance could not be read.Example: 8

Error responses

Condition	Status	Message
`chain` missing	400	`chain query param is required`
Chain not recognised	400	`invalid chain: <chain>`
Chain not supported for subwallets	400	`Unsupported chain for subwallets`
Currency not supported on that chain	400	`Unsupported currency for chain <chain>`
Address not valid or network not supported	400	Message describing the problem
Wallet service unavailable	503	`Wallet service is temporarily unavailable. Please try again.`

This endpoint has a tighter limit of 30 requests per minute, in addition to the subwallet limit. See Rate limits.

Authorizations

authorization

string

header

required

Signed (HMAC) authentication. Required headers: x-access-id, x-request-id (UUID v4), x-timestamp (ISO 8601, must be within 5 minutes of server time), and authorization: the Base64 HMAC-SHA256 of the JSON string {"timeStamp":"","requestId":"","accessId":""} (keys in that order, no whitespace) using your access secret. The request body, method and path are not signed. The API key must be linked to an outlet.

Headers

authorization

string

required

Base64-encoded HMAC-SHA256 signature of {"timeStamp":"","requestId":"","accessId":""}, signed with your access secret. The request body is not part of the signature.

x-timestamp

string<date-time>

required

ISO 8601 timestamp; must be within 5 minutes of server time

x-request-id

string<uuid>

required

A unique UUID v4 per request

x-access-id

string

required

Path Parameters

address

string

required

Blockchain address.

Query Parameters

chain

enum<string>

required

Available options:

ethereum,

tron,

bitcoin

currency

string

Currency symbol, case-insensitive. Omit for all balances.

Response

Balance

status

string

required

Example:

"success"

message

string

required

Example:

"success"

data

All balances (no currency) · object

required

All balances (no currency)
Single balance (currency given)

Show child attributes

Payment

System

Agents

Conversions

Payouts

Subwallets

Webhooks

On-ramp

Get Address Balance

Example

Headers

Path Parameters

Query Parameters

Response

Error responses

Authorizations

Headers

Path Parameters

Query Parameters

Response

​Example

​Headers

​Path Parameters

​Query Parameters

​Response

​Error responses

Authorizations

Headers

Path Parameters

Query Parameters

Response

Example

Headers

Path Parameters

Query Parameters

Response

Error responses