eth_getBalance - Flashblocks

Example code for the eth_getBalance Flashblocksmethod. Complete guide on how to use eth_getBalance Flashblocks in GetBlock Web3 documentation.

This returns the ETH balance of an address in wei. When called with "pending", includes the effect of every transaction preconfirmed into the latest Flashblock — usually within 200ms (Base) or 250ms (Optimism) of the user's submission. Applications that update balance UIs on the pending tag give users near-instant feedback that a transfer has landed.

Parameters

Parameter	Type	Required	Description
address	DATA (20 bytes)	Yes	Address to check
block	QUANTITY	TAG	Yes

Request Example

cURL

curl --location --request POST 'https://go.getblock.io/<ACCESS-TOKEN>/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": [
        "0x7a25d0f0Ff6a25f36De0a19C3d5f6dC2C6EAeD6a",
        "pending"
    ],
    "id": "getblock.io"
}'

JavaScript (Axios)

import axios from 'axios';

const data = JSON.stringify({
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": [
        "0x7a25d0f0Ff6a25f36De0a19C3d5f6dC2C6EAeD6a",
        "pending"
    ],
    "id": "getblock.io"
});

const config = {
    method: 'post',
    url: 'https://go.getblock.io/<ACCESS-TOKEN>/',
    headers: {
        'Content-Type': 'application/json'
    },
    data: data
};

axios(config)
    .then(response => console.log(JSON.stringify(response.data, null, 2)))
    .catch(error => console.log(error));

Python (Requests)

import requests
import json

url = "https://go.getblock.io/<ACCESS-TOKEN>/"

payload = json.dumps({
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": [
        "0x7a25d0f0Ff6a25f36De0a19C3d5f6dC2C6EAeD6a",
        "pending"
    ],
    "id": "getblock.io"
})

headers = {
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, data=payload)
print(response.text)

Rust (Reqwest)

use reqwest::Client;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();

    let payload = json!({
        "jsonrpc": "2.0",
        "method": "eth_getBalance",
        "params": [
                "0x7a25d0f0Ff6a25f36De0a19C3d5f6dC2C6EAeD6a",
                "pending"
        ],
        "id": "getblock.io"
});

    let response = client
        .post("https://go.getblock.io/<ACCESS-TOKEN>/")
        .header("Content-Type", "application/json")
        .json(&payload)
        .send()
        .await?;

    let result: serde_json::Value = response.json().await?;
    println!("{:#?}", result);

    Ok(())
}

Response Example

{
    "jsonrpc": "2.0",
    "id": "getblock.io",
    "result": "0x1bc16d674ec80000"
}

Response Parameters

Field	Type	Description
result	QUANTITY	Balance in wei (hex). Divide by 10^18 to get ETH

Use Cases

• Wallet UIs showing near-instant balance updates after a transfer

• Payment applications confirming a payment has been received before block seal

• Trading bots that need to know current available balance including unsealed transfers

Error Handling

Status Code	Error Message	Cause
403	Forbidden	Missing or invalid <ACCESS-TOKEN>
-32602	Invalid params	Request parameters are missing or malformed
-32601	Method not found	Method does not exist or is not enabled on this endpoint. Confirm your endpoint is Flashblocks-aware.
-32603	Internal error	Server-side error while processing the request
429	Too Many Requests	Rate limit exceeded for your plan
-32602	Invalid address	Address is not a valid 20-byte hex string

SDK Integration

ethers.js

import { ethers } from 'ethers';

const provider = new ethers.JsonRpcProvider('https://go.getblock.io/<ACCESS-TOKEN>/');

// Generic JSON-RPC call — 'pending' returns Flashblocks-preconfirmed state:
const result = await provider.send('eth_getBalance', ["0x7a25d0f0Ff6a25f36De0a19C3d5f6dC2C6EAeD6a", "pending"]);
console.log(result);

// Many standard methods have typed wrappers on ethers Provider that accept 'pending':
// provider.getBalance(addr, 'pending'), provider.getTransactionCount(addr, 'pending'), etc.

viem

import { createPublicClient, http } from 'viem';

const client = createPublicClient({
    transport: http('https://go.getblock.io/<ACCESS-TOKEN>/')
});

// viem's read methods accept blockTag: 'pending' for Flashblocks-preconfirmed state:
const result = await client.request({
    method: 'eth_getBalance',
    params: ["0x7a25d0f0Ff6a25f36De0a19C3d5f6dC2C6EAeD6a", "pending"]
});
console.log(result);

// Typed wrappers also accept blockTag: 'pending':
// client.getBalance({ address, blockTag: 'pending' })
// client.getBlock({ blockTag: 'pending' })