Get Balance with Carbium

Use this page when you need the smallest useful RPC read: fetch a wallet's SOL balance through Carbium RPC and convert lamports into SOL.

This is a DEVELOPMENT sample, not a dashboard walkthrough. If you only need to prove your key works, start with Quick Start RPC. If you need a broader list of methods, use Example Calls.

Part of the Carbium Solana infrastructure stack.

---

What this example does

The flow is intentionally small:

1. read the RPC key from a backend environment variable
2. call Carbium's current JSON-RPC endpoint
3. request getBalance for one wallet public key
4. convert the lamport result into SOL
5. handle RPC errors without logging secrets

Use this before you add transaction submission, swap execution, or a larger polling loop.

---

Endpoint and key

Use the current Carbium RPC endpoint format:

https://rpc.carbium.io/?apiKey=YOUR_RPC_KEY

Store the key outside source code:

export CARBIUM_RPC_KEY="your-rpc-key"
export WALLET_ADDRESS="your-solana-wallet-public-key"

🔐 Do not paste RPC keys into frontend code, public repos, screenshots, or support logs. For storage, rotation, and exposure response, use API Key Security Best Practices.

---

Curl smoke test

A raw JSON-RPC call is the fastest way to separate endpoint problems from SDK problems.

curl -X POST "https://rpc.carbium.io/?apiKey=$CARBIUM_RPC_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"jsonrpc\": \"2.0\",
    \"id\": 1,
    \"method\": \"getBalance\",
    \"params\": [
      \"$WALLET_ADDRESS\",
      { \"commitment\": \"confirmed\" }
    ]
  }"

A successful response uses lamports:

{
  "jsonrpc": "2.0",
  "result": {
    "context": { "slot": 341197804 },
    "value": 5431298372
  },
  "id": 1
}

Convert lamports to SOL by dividing by 1_000_000_000.

---

Python example

Install the Solana Python client:

python -m pip install solana solders

Then run a direct balance read:

import os
from solana.rpc.api import Client
from solders.pubkey import Pubkey

LAMPORTS_PER_SOL = 1_000_000_000

rpc_key = os.environ["CARBIUM_RPC_KEY"]
wallet_address = os.environ["WALLET_ADDRESS"]

client = Client(f"https://rpc.carbium.io/?apiKey={rpc_key}")
wallet = Pubkey.from_string(wallet_address)

response = client.get_balance(wallet, commitment="confirmed")

if response.value is None:
    raise RuntimeError(f"getBalance returned no value: {response}")

balance_sol = response.value / LAMPORTS_PER_SOL
print(f"Wallet balance: {balance_sol:.9f} SOL")

Example output:

Wallet balance: 5.431298372 SOL

The exact number depends on the wallet and the commitment level at the time of the request.

---

Choose the right commitment

For most balance reads, start with confirmed.

Commitment	Use for balance reads when...
processed	The UI needs the freshest possible signal and can re-check quickly.
confirmed	The value drives normal wallet, bot, dashboard, or backend decisions.
finalized	The value is used for accounting, reconciliation, or slower settlement checks.

If this choice affects product behavior, read Solana Commitment Levels before shipping.

---

Production notes

A balance read is simple, but repeated balance reads can still create production issues.

Risk	What to do
Polling too often	Cache short-lived UI reads and avoid refreshing every wallet every slot.
Treating stale data as final	Use confirmed for live decisions and reconcile with finalized where needed.
Logging full URLs	Redact the apiKey query value before storing or sharing logs.
Retrying every failure instantly	Use backoff and classify failures before widening retries.
Reading token balances through SOL balance calls	Use token-account methods when you need SPL token balances.

For 429, timeout, JSON-RPC, or support-payload triage, use RPC Errors Reference and Solana RPC Rate Limits Explained.

---

When to move beyond this sample

This page only owns the first balance read. Move to the next doc when the question changes.

Next question	Go to
How do I get connected from zero?	Quick Start RPC
Which commitment should the app use?	Solana Commitment Levels
How do I list token accounts?	Example Calls
How do I send or confirm transactions?	Sending Transactions through Carbium RPC
How should the app behave during RPC failures?	RPC Errors Reference

🔶 Once one balance read works, keep the same server-side key pattern for the rest of your Carbium RPC integration.