💵 Get a single TRC20 balance

Code samples

GET /api/v1/trx/account/balance/trc20/{address}/{contractAddress}

curl 'https://settla.net/api/v1/trx/account/balance/trc20/TMuA6YqfCeX8EhbfYEg5y7S4DqzSJireY9/TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t' \
  -H 'X-API-Key: $SETTLA_API_KEY' \
  -H 'Accept: application/json'

Returns one address's balance of one TRC20 contract, with the token's metadata resolved. Unlike /account/{address}/balance, this endpoint is not limited to the curated whitelist: the balance is read straight off the contract, so any TRC20 address works. The metadata, however, still comes from the whitelist — for a contract outside it symbol, name and decimals all come back as null while balance is correct. In that case you have to know the token's precision yourself. balance is always the raw integer unit as a decimal string; divide by 10 ** decimals to display it. Both path segments are checksum-validated before the node is called, so a malformed address fails fast with 400.

🛠️ Parameters

Example responses

200 Response — USDT — metadata resolved

{
  "address": "TMuA6YqfCeX8EhbfYEg5y7S4DqzSJireY9",
  "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "balance": "3100000",
  "symbol": "USDT",
  "decimals": 6,
  "name": "Tether USD"
}

200 Response — JST — balance only, metadata null

{
  "address": "TMuA6YqfCeX8EhbfYEg5y7S4DqzSJireY9",
  "contract_address": "TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9",
  "balance": "0",
  "symbol": null,
  "decimals": null,
  "name": null
}

400 Response — badAddress

{
  "error": "Invalid address."
}

400 Response — badContract

{
  "error": "Invalid contract address."
}

500 Response — nodeUnreachable

{
  "error": "Could not connect to TRX node."
}

500 Response — Node answered but the constant call produced no value

{
  "error": "Failed to fetch TRC20 balance from node."
}

🔁 Responses

🔄 Response Schema

Status Code 200

Status Code 400

Status Code 500