Balances

Note: only Ethereum and BSC mainnet are supported right now, but more chains will be soon to come.

Request Format:

Covalent - Balances API - Free plan

GET: https://open-platform.nodereal.io/{{apiKey}}/covalenthq/v1/{{chainName}}/address/{{walletAddress}}/balances_v2/

Covalent - Balances API (Premium)

GET: https://open-platform.nodereal.io/{{apiKey}}/covalenthq-premium/v1/{{chainName}}/address/{{walletAddress}}/balances_v2/

Path Parameters:

Name	Description
apiKey	String - your NodeReal API Key, consisting of 32 characters. To find your API key, you could refer to this guidance Find API key & endpoint.
chainName	String: name of the chain you are querying List of supported values: eth-mainnet, bsc-mainnet (See Covalent’s supported networks: https://www.covalenthq.com/docs/networks/)
walletAddress	String: Wallet or contract address (can be in ENS format). (e.g. 0xe33b778665a1C1e9f6318abF11eF4889C0911FD7)

Query Parameters:

Name	Description
(optional) nft	Boolean - Set to true to return ERC721 and ERC1155 assets. Default value: “false”.
(optional) no-nft-fetch	Boolean - If true, skips fetching NFT metadata, which may result in a faster response. Defaults to false, and only applies when nft=true.
(optional) quote-currency	String - Defaults to USD. Returns values denominated in the quote-currency. You can change it by selecting one of the 12 currencies supported: (ARS, AUD, USD, CAD, KRW, SGD, RUB, EUR, JPY, NGN, CHF, GBP).
(optional) format	String - Defaults to ‘JSON’, which returns data in JSON format. If specified to be ‘CSV’, will return data in CSV format.

Example with query params:
https://open-platform.nodereal.io/{{apiKey}}/covalenthq/v1/eth-mainnet/address/0xe33b778665a1C1e9f6318abF11eF4889C0911FD7/balances_v2/?nft=true&no-nft-fetch=true&quote-currency=SGD&format=CSV

Example

Request

curl --location --request GET 'https://open-platform.nodereal.io/{{apiKey}}/covalenthq/v1/eth-mainnet/address/0x0110A04Fe49534249F87971192989E00D5d3715d/balances_v2/?nft=true' \

Result

{
    "data": {
        "address": "0x0110a04fe49534249f87971192989e00d5d3715d",
        "updated_at": "2022-11-24T02:40:34.674231102Z",
        "next_update_at": "2022-11-24T02:45:34.674231152Z",
        "quote_currency": "USD",
        "chain_id": 1,
        "items": [
            {
                "contract_decimals": 6,
                "contract_name": "Tether USD",
                "contract_ticker_symbol": "USDT",
                "contract_address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
                "supports_erc": [
                    "erc20"
                ],
                "logo_url": "https://logos.covalenthq.com/tokens/1/0xdac17f958d2ee523a2206206994597c13d831ec7.png",
                "last_transferred_at": "2022-11-09T01:38:11Z",
                "native_token": false,
                "type": "stablecoin",
                "balance": "90018299",
                "balance_24h": "90018299",
                "quote_rate": 1.0008739,
                "quote_rate_24h": 0.99286574,
                "quote": 90.09697,
                "quote_24h": 89.37608,
                "nft_data": null
            },
            {
                "contract_decimals": 18,
                "contract_name": "Ether",
                "contract_ticker_symbol": "ETH",
                "contract_address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
                "supports_erc": null,
                "logo_url": "https://www.covalenthq.com/static/images/icons/display-icons/ethereum-eth-logo.png",
                "last_transferred_at": null,
                "native_token": true,
                "type": "cryptocurrency",
                "balance": "9128773363402209",
                "balance_24h": "2405698964520082",
                "quote_rate": 1185.9159,
                "quote_rate_24h": 1174.5662,
                "quote": 10.825957,
                "quote_24h": 2.8256526,
                "nft_data": null
            },
            {
                "contract_decimals": 0,
                "contract_name": "Metopian SBT",
                "contract_ticker_symbol": "MSBT",
                "contract_address": "0xd5b2698acae508a30ef19b1a8d44081754aa1923",
                "supports_erc": [
                    "erc20",
                    "erc721"
                ],
                "logo_url": "https://logos.covalenthq.com/tokens/1/0xd5b2698acae508a30ef19b1a8d44081754aa1923.png",
                "last_transferred_at": "2022-11-03T12:44:47Z",
                "native_token": false,
                "type": "nft",
                "balance": "1",
                "balance_24h": null,
                "quote_rate": 0.0,
                "quote_rate_24h": null,
                "quote": 0.0,
                "quote_24h": null,
                "nft_data": [
                    {
                        "token_id": "163",
                        "token_balance": "1",
                        "token_url": "data:application/json;base64,eyJuYW1lIjoiTWV0b3BpYW4gU0JUIiwiZGVzY3JpcHRpb24iOiIiLCJpbWFnZSI6Imh0dHBzOi8vYWkubWV0b3BpYS54eXovc2J0LWdlbmVyYXRvcj90aXRsZT1EYXRhJTIwR3VhcmRpYW4mZGVzY3JpcHRpb249WW91ciUyMFdlYjMlMjBpZGVudGl0eSUyMHVubG9ja2VkISUyMENvbmdyYXRzLCUyMERhdGElMjBHdWFyZGlhbiEmc3BhY2U9TWV0b3BpYSZzaWduZXI9bWV0b3BpYW50ZWNoLmV0aCZmZWF0dXJlZEltYWdlQ0lEPVFtWDNMcVU4ZGZxWG84TkxtZ3dmZ0hVdUt6dFB0NGtNdFJ3MmpTVVJjdThqN3omaWQ9MTYzIiwgImF0dHJpYnV0ZXMiOlt7InRyYWl0X3R5cGUiOiAiVGl0bGUiLCAidmFsdWUiOiAiRGF0YSBHdWFyZGlhbiJ9LHsidHJhaXRfdHlwZSI6IkRlc2NyaXB0aW9uIiwgInZhbHVlIjoiWW91ciBXZWIzIGlkZW50aXR5IHVubG9ja2VkISBDb25ncmF0cywgRGF0YSBHdWFyZGlhbiEifSx7InRyYWl0X3R5cGUiOiJTcGFjZSIsICJ2YWx1ZSI6Ik1ldG9waWEifSx7InRyYWl0X3R5cGUiOiJTaWduZXIiLCAidmFsdWUiOiJtZXRvcGlhbnRlY2guZXRoIn1dfQ==",
                        "supports_erc": [
                            "erc20",
                            "erc721"
                        ],
                        "token_price_wei": null,
                        "token_quote_rate_eth": null,
                        "original_owner": "0x0110a04fe49534249f87971192989e00d5d3715d",
                        "external_data": {
                            "name": "Metopian SBT",
                            "description": "",
                            "image": "https://ai.metopia.xyz/sbt-generator?title=Data%20Guardian&description=Your%20Web3%20identity%20unlocked!%20Congrats,%20Data%20Guardian!&space=Metopia&signer=metopiantech.eth&featuredImageCID=QmX3LqU8dfqXo8NLmgwfgHUuKztPt4kMtRw2jSURcu8j7z&id=163",
                            "image_256": "https://image-proxy.svc.prod.covalenthq.com/cdn-cgi/image/width=256,fit/https://ai.metopia.xyz/sbt-generator?title=Data%20Guardian&description=Your%20Web3%20identity%20unlocked!%20Congrats,%20Data%20Guardian!&space=Metopia&signer=metopiantech.eth&featuredImageCID=QmX3LqU8dfqXo8NLmgwfgHUuKztPt4kMtRw2jSURcu8j7z&id=163",
                            "image_512": "https://image-proxy.svc.prod.covalenthq.com/cdn-cgi/image/width=512,fit/https://ai.metopia.xyz/sbt-generator?title=Data%20Guardian&description=Your%20Web3%20identity%20unlocked!%20Congrats,%20Data%20Guardian!&space=Metopia&signer=metopiantech.eth&featuredImageCID=QmX3LqU8dfqXo8NLmgwfgHUuKztPt4kMtRw2jSURcu8j7z&id=163",
                            "image_1024": "https://image-proxy.svc.prod.covalenthq.com/cdn-cgi/image/width=1024,fit/https://ai.metopia.xyz/sbt-generator?title=Data%20Guardian&description=Your%20Web3%20identity%20unlocked!%20Congrats,%20Data%20Guardian!&space=Metopia&signer=metopiantech.eth&featuredImageCID=QmX3LqU8dfqXo8NLmgwfgHUuKztPt4kMtRw2jSURcu8j7z&id=163",
                            "animation_url": null,
                            "external_url": null,
                            "attributes": [
                                {
                                    "trait_type": "Title",
                                    "value": "Data Guardian"
                                },
                                {
                                    "trait_type": "Description",
                                    "value": "Your Web3 identity unlocked! Congrats, Data Guardian!"
                                },
                                {
                                    "trait_type": "Space",
                                    "value": "Metopia"
                                },
                                {
                                    "trait_type": "Signer",
                                    "value": "metopiantech.eth"
                                }
                            ],
                            "owner": null
                        },
                        "owner": "0x0110a04fe49534249f87971192989e00d5d3715d",
                        "owner_address": null,
                        "burned": null
                    }
                ]
            },
            ...
        ],
        "pagination": null
    },
    "error": false,
    "error_message": null,
    "error_code": null
}

Frequently Asked Questions:

Why is the ‘balance’ value so large in my response?
The balance fields are denominated in Wei. To get the standard unit in Eth, do the following calculation: balance/10^contractDecimal
What is the current API rate limits?
Free tier: 4 requests per second.
Paid tier(hasn't enabled yet): 50 requests per second.
What do the following error codes mean?
404: Page Unavailable - The API server cannot find the requested API resource. Check your request endpoint.
406: Address Will Predictably Timeout - The API returns this error for addresses where requests will likely timeout due to, as an example, too many transactions associated with the address.
429: Too Many Requests - The client has surpassed its rate limit. This may also be indicated by the server 503: Network Error.
500: Request Timeout - This error response is given when the query will take longer than approximately 90 seconds.
503: Network Error - The API server cannot handle the request at the time, which might be due to a high number of concurrent requests or if a server is momentarily down. Retry your request in a couple minutes or reduce the number of concurrent requests.
507: Insufficient Storage - The API server is unreachable to new queries as the backlog of existing queries is full. We are likely aware of the issue and reviewing the queries consuming the resources.
562: Failed to connect to upstream third-party service - The API server can’t reach the external server where the data is hosted at the moment. This is intentionally done in order to avoid returning erroneous data.
How do I fix the CORS header ‘Access-Control-Allow-Origin’ missing error?
CORS is an HTTP header-based mechanism that allows a server to indicate any origins (domain, scheme, or port) other than its own from which a browser should permit loading resources. If you are running your app locally on localhost, you may run into this error when trying to make API calls.
One workaround is to use this extension.
Why is the logo_url sometimes missing in the response of Balances endpoint?
We fetch the logos from the Trust Wallet repository. If your logo is not available there, the token balances endpoint will not be able to fetch it.
Use the Trust Wallet Assets web app to add your token and corresponding logo.
Why does the call to Get token balances for address sometimes timeout when using the nft=true option?
Timouts using the nft=trueoption are likely due to corresponding timeouts with an external service call made by our API to fetch the NFT metadata. You can confirm this by making the same call and setting no-nft-fetch=trueand see if that returns successfully.
What if I need more help?
Head down to the #📩｜support-ticket channel of NodeReal’s discord! Our staff will be there to help you.