---
updatedAt: 2026-06-10T11:32:31.000Z
agentTools:
  projectIndex: https://docs.lmnl.app/llms.txt
---

# Retrieve an address balance

This API is a request to retrieve <<glossary:native coin>> or <<glossary:token>> balance of a specific address or for a paginated list of addresses in your <<glossary:deposit wallet>>. <br><br> This API doesn't retrieve a list of address balances. To retrieve balance of an entire wallet, use the [Retrieve a wallet balance](https://docs.lmnl.app/reference/getwalletbalance) API. <br> <br> For Stellar, Cosmos, and Ripple chains, which only have a single address per wallet, use the [Retrieve a wallet balance](https://docs.lmnl.app/reference/getwalletbalance) API instead.

This API reference helps retrieve the native coin and token balance of a wallet’s address only, such as in case of a deposit wallet. It retrieves the coin or token balance using either the address (wallet address) field or a paginated list of addresses using the `pagination` object’s `pageNumber` and `pageSize` fields.

* We recommend using this API when you want to retrieve the balance of a deposit wallet’s list of addresses.
* In case you want to request the total wallet balance, i.e., including both native coins and tokens for all addresses in the wallet, we recommend using the [Retrieve a wallet balance](https://docs.lmnl.app/reference/getwalletbalance) API. Example: For Stellar, Cosmos, and Ripple chains, which only have a single address per wallet.

# API use cases

You can use the API to retrieve the balance of either native coins or tokens from a single address or a list of addresses, as explained in the following use cases.

## Retrieve native coin balance

* **Single address query**: You can retrieve the native coin balance for a single address, using the following request body.
  ```json
  {
      "wallet":{
          "coin": "eth",
          "walletId":1
      },
      "getAddressBalanceOption":{
          "address":"0xec69e15335c1f7a0a4733b504abc327f81baf8b5"
      }
  }
  ```
* **Paginated address query**: You can retrieve native coin balance for a paginated list of addresses, using the following request body.
  ```json
  {
      "wallet":{
          "coin": "eth",
          "walletId":1
      },
      "getAddressBalanceOption":{
         "pagination":{
                      "pageNumber":1,
                      "pageSize":50
                  }
      }
  }
  ```

## Retrieve token balance

* **Single address query** - You can retrieve the token balance for a single address, using the following request body. The body includes an additional parameter `isTokenBalance`. If you set its value to `true`, the API retrieves the token balance.
  ```json
  {
      "wallet":{
          "coin": "eth",
          "walletId":1
      },
      "getAddressBalanceOption":{
          "address":"0x4014c023192ef37a91adcea4ac2fdd90914bd76f",
          "isTokenBalance":true
      }
  }
  ```
* `Paginated address query` - You can retrieve token balance for a paginated list of addresses, using the following request body. The body includes an additional parameter `isTokenBalance`. If you set its value to `true`, the API retrieves the token balance.
  ```json
  {
      "wallet":{
          "coin": "eth",
          "walletId":1
      },
      "getAddressBalanceOption":{
          "pagination":{
                      "pageNumber":1,
                      "pageSize":10
                  },
          "isTokenBalance":true
      }
  }
  ```

<br />

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "API REFERENCES",
    "contact": {},
    "version": "8"
  },
  "servers": [
    {
      "url": "https://api-sdk.lmnl.dev",
      "variables": {}
    }
  ],
  "tags": [
    {
      "name": "Addresses"
    }
  ],
  "paths": {
    "/api/wallet/address-balance": {
      "post": {
        "tags": [
          "Addresses"
        ],
        "summary": "Retrieve an address balance",
        "description": "This API is a request to retrieve <<glossary:native coin>> or <<glossary:token>> balance of a specific address or for a paginated list of addresses in your <<glossary:deposit wallet>>. <br><br> This API doesn't retrieve a list of address balances. To retrieve balance of an entire wallet, use the [Retrieve a wallet balance](https://docs.lmnl.app/reference/getwalletbalance) API. <br> <br> For Stellar, Cosmos, and Ripple chains, which only have a single address per wallet, use the [Retrieve a wallet balance](https://docs.lmnl.app/reference/getwalletbalance) API instead.",
        "operationId": "GetAddressBalance",
        "parameters": [],
        "requestBody": {
          "description": "",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Get-Address-Balance-Object-Model-Request"
                  },
                  {
                    "example": {
                      "wallet": {
                        "coin": "eth",
                        "walletId": 15000
                      },
                      "getAddressBalanceOption": {
                        "address": "0xec69e15335c1f7a0a4733b504abc327f81baf8b5",
                        "pagination": {
                          "pageNumber": 1,
                          "pageSize": 5
                        }
                      }
                    }
                  }
                ]
              },
              "example": {
                "wallet": {
                  "coin": "eth",
                  "walletId": 15000
                },
                "getAddressBalanceOption": {
                  "address": "0xec69e15335c1f7a0a4733b504abc327f81baf8b5",
                  "pagination": {
                    "pageNumber": 1,
                    "pageSize": 5
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Get-Address-Balance-by-Address-Response"
                    },
                    {
                      "example": {
                        "success": true,
                        "data": {
                          "AddressBalance": {
                            "address": "0x017208E63ec387461C7e8f20bA9C6F9Dec939cfe",
                            "type": "receive",
                            "path": "m/0/3",
                            "balance": "0.00012600",
                            "walletid": 15000
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "success": true,
                  "data": {
                    "AddressBalance": {
                      "address": "0x017208E63ec387461C7e8f20bA9C6F9Dec939cfe",
                      "type": "receive",
                      "path": "m/0/3",
                      "balance": "0.00012600",
                      "walletid": 15000
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "description": "This indicates whether the address balance is successfully retrieved or not.",
                      "example": false
                    },
                    "data": {
                      "type": "object",
                      "example": {}
                    },
                    "message": {
                      "type": "string",
                      "description": "A short description of the error.",
                      "example": ""
                    },
                    "code": {
                      "type": "string",
                      "description": "The error code for the API failure.",
                      "example": ""
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "description": "This indicates whether the address balance is successfully retrieved or not.",
                      "example": false
                    },
                    "data": {
                      "type": "object",
                      "description": "The details related to the error response.",
                      "additionalProperties": true,
                      "example": {}
                    },
                    "message": {
                      "type": "string",
                      "description": "A short description of the error.",
                      "example": "{\"success\":false,\"data\":{},\"message\":\"No record found for the specified wallet.\",\"code\":\"\"}"
                    },
                    "code": {
                      "type": "string",
                      "description": "The code of the error.",
                      "example": ""
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false,
        "security": [
          {
            "basic": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Get-Address-Balance-by-Address-Response": {
        "title": "Get-Address-Balance-by-Address-Response",
        "required": [
          "success",
          "data"
        ],
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "This indicates whether the address balance was successfully retrieved or not.",
            "example": true
          },
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Data29"
              },
              {}
            ]
          }
        },
        "example": {
          "success": true,
          "data": {
            "AddressBalance": {
              "address": "0x017208E63ec387461C7e8f20bA9C6F9Dec939cfe",
              "type": "receive",
              "path": "m/0/3",
              "balance": "0.00012600",
              "walletid": 15000
            }
          }
        }
      },
      "Data29": {
        "title": "Data29",
        "required": [
          "AddressBalance"
        ],
        "type": "object",
        "properties": {
          "AddressBalance": {
            "allOf": [
              {
                "$ref": "#/components/schemas/AddressBalanceList"
              },
              {}
            ]
          }
        },
        "example": {
          "AddressBalance": {
            "address": "0x017208E63ec387461C7e8f20bA9C6F9Dec939cfe",
            "type": "receive",
            "path": "m/0/3",
            "balance": "0.00012600",
            "walletid": 15000
          }
        }
      },
      "Get-Address-Balance-Object-Model-Request": {
        "title": "Get-Address-Balance-Object-Model-Request",
        "required": [
          "wallet",
          "getAddressBalanceOption"
        ],
        "type": "object",
        "properties": {
          "wallet": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Wallet-Native-Object"
              },
              {}
            ]
          },
          "getAddressBalanceOption": {
            "allOf": [
              {
                "$ref": "#/components/schemas/GetAddressBalanceOption-Object-Request"
              },
              {}
            ]
          }
        }
      },
      "Pagination-Object-Request": {
        "title": "Pagination-Object-Request",
        "required": [
          "pageNumber",
          "pageSize"
        ],
        "type": "object",
        "properties": {
          "pageNumber": {
            "type": "integer",
            "description": "Enter the desired page number for paginated results.",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "description": "Enter the number of entries or results you require per page.",
            "format": "int32"
          }
        },
        "example": {
          "pageNumber": 1,
          "pageSize": 5
        }
      },
      "AddressBalanceList": {
        "title": "AddressBalanceList",
        "required": [
          "address",
          "type",
          "path",
          "balance",
          "walletid"
        ],
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "description": "The blockchain address for which the balance was requested.",
            "example": null
          },
          "type": {
            "type": "string",
            "description": "The type of address. For example, in a deposit wallet, the address is a \"receive\" type."
          },
          "path": {
            "type": "string",
            "description": "The path of the specified address.",
            "example": 3
          },
          "balance": {
            "type": "string",
            "description": "The total native asset balance of the address.",
            "example": 0
          },
          "walletid": {
            "type": "integer",
            "description": "The unique identifier (ID) of the deposit wallet containing the address.",
            "format": "int32"
          },
          "tokens": {
            "type": "object",
            "properties": {
              "address": {
                "type": "string",
                "description": "The unique blockchain address of the token.",
                "example": 5.570420786032324e+47
              },
              "token_identifier": {
                "type": "string",
                "description": "The unique identifier of the token.",
                "example": 1.1707488524310892e+48
              },
              "balance": {
                "type": "string",
                "description": "The token balance in the address.",
                "example": 0
              },
              "balance_usd": {
                "type": "string",
                "description": "The token balance in USD.",
                "example": 0
              },
              "wallet_id": {
                "type": "integer",
                "description": "The unique identifier (ID) of the deposit wallet containing the address.",
                "format": "int32",
                "example": 26247
              },
              "decimal_places": {
                "type": "string",
                "description": "The number of decimal places used for the asset (e.g., 18 for ETH).",
                "example": 18
              },
              "symbol": {
                "type": "string",
                "description": "The symbol of the token.",
                "example": "USDT"
              }
            }
          }
        },
        "example": {
          "address": "0xB9dF6D174d6f1f3A61484762E7131F46Ec85b0d1",
          "type": "receive",
          "path": "m/0/0",
          "balance": "0.00012600",
          "walletid": 15000
        }
      },
      "GetAddressBalanceOption-Object-Request": {
        "title": "GetAddressBalanceOption-Object-Request",
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "description": "Enter the specific blockchain address for balance inquiry."
          },
          "pagination": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Pagination-Object-Request"
              },
              {}
            ]
          },
          "isTokenBalance": {
            "type": "boolean",
            "description": "Set its value to true if seeking both the native and token balances for the specified address.",
            "default": true
          }
        },
        "example": {
          "address": "0xec69e15335c1f7a0a4733b504abc327f81baf8b5",
          "pagination": {
            "pageNumber": 1,
            "pageSize": 5
          },
          "isTokenBalance": true
        }
      },
      "coinEnum2": {
        "title": "coinEnum2",
        "enum": [
          "eth",
          "btc",
          "doge",
          "bch",
          "ltc",
          "matic",
          "xrp",
          "xlm",
          "trx",
          "bnb",
          "uatom",
          "sol",
          "xdc",
          "aeth",
          "avax",
          "oeth",
          "ethw",
          "algo",
          "beth",
          "kaia"
        ],
        "type": "string",
        "description": "Enter the abbreviated form of the cryptocurrency associated with the wallet. Note that for \"arb\", enter \"aeth\"."
      },
      "Wallet-Native-Object": {
        "title": "Wallet-Native-Object",
        "required": [
          "coin",
          "walletId"
        ],
        "type": "object",
        "properties": {
          "coin": {
            "allOf": [
              {
                "$ref": "#/components/schemas/coinEnum2"
              },
              {}
            ]
          },
          "walletId": {
            "type": "integer",
            "description": "Enter the unique identifier (ID) of the wallet.",
            "format": "int32"
          }
        }
      }
    },
    "securitySchemes": {
      "basic": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "security": []
}
```