Cara Mendapatkan Saldo Dompet

Wallet API masih dalam versi Beta. Endpoint dan format respons dapat berubah.

Ikhtisar

Endpoint Wallet Balances mengambil semua kepemilikan token dan NFT dari sebuah dompet Solana — SOL, token SPL, Token-2022, dan NFT — beserta harga dalam USD, logo, dan metadata. Hasil diurutkan berdasarkan nilai USD secara menurun: token dengan data harga ditampilkan lebih dahulu, diikuti oleh token tanpa harga. Endpoint ini mengembalikan hingga 100 token per permintaan, sehingga paginasi harus dilakukan secara manual. Gunakan parameter page untuk mengambil halaman tambahan dan baca pagination.hasMore untuk mengetahui apakah masih ada hasil lainnya. Setiap permintaan merupakan satu panggilan API dan dikenai biaya 100 kredit.

Harga USD bersumber dari DAS dan diperbarui setiap jam, mencakup 10.000 token teratas berdasarkan kapitalisasi pasar. pricePerToken dan usdValue bernilai null untuk token yang tidak didukung. Harga merupakan estimasi, bukan harga pasar waktu nyata.

Kapan menggunakannya

Gunakan Wallet Balances API saat Anda perlu:

Menampilkan kepemilikan portofolio: tampilkan seluruh kepemilikan token dan NFT milik pengguna.
Menghitung nilai USD: dapatkan valuasi portofolio dengan harga yang diperbarui setiap jam.
Membuat antarmuka dompet: dukung dasbor dompet dan daftar aset.
Melacak kepemilikan token: pantau saldo token tertentu di berbagai dompet.
Analitik portofolio: analisis distribusi dan konsentrasi kepemilikan.
Pelaporan pajak: buat rekam kondisi kepemilikan untuk keperluan pajak.

Mulai cepat

Kueri saldo dasar

Dapatkan semua saldo token untuk sebuah dompet beserta nilai USD:

JavaScript
Python
cURL

const getWalletBalances = async (address) => {
  const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY`;

  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const data = await response.json();

  const solBalance = data.balances[0]; // SOL is always first when showNative=true
  console.log(`SOL Balance: ${solBalance.balance} SOL ($${solBalance.usdValue})`);
  console.log(`Page ${data.pagination.page} Total Value: $${data.totalUsdValue}`);
  console.log(`Token Count (this page): ${data.balances.length}`);

  // Display top holdings
  data.balances.slice(0, 5).forEach(token => {
    console.log(`${token.symbol}: ${token.balance} ($${token.usdValue || 'N/A'})`);
  });

  return data;
};

getWalletBalances("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY");

import requests

def get_wallet_balances(address: str):
    url = f"https://api.helius.xyz/v1/wallet/{address}/balances"
    headers = {"X-Api-Key": "YOUR_API_KEY"}

    response = requests.get(url, headers=headers)
    response.raise_for_status()

    data = response.json()

    sol_balance = data['balances'][0]  # SOL is always first when showNative=true
    print(f"SOL Balance: {sol_balance['balance']} SOL (${sol_balance['usdValue']})")
    print(f"Page {data['pagination']['page']} Total Value: ${data['totalUsdValue']}")
    print(f"Token Count (this page): {len(data['balances'])}")

    # Display top holdings
    for token in data['balances'][:5]:
        usd_value = token.get('usdValue', 'N/A')
        print(f"{token['symbol']}: {token['balance']} (${usd_value})")

    return data

get_wallet_balances("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY")

curl "https://api.helius.xyz/v1/wallet/86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY/balances?api-key=YOUR_API_KEY"

Sertakan NFT dalam hasil

Dapatkan token dan NFT dalam satu permintaan dengan showNfts=true:

JavaScript
Python

const getWalletWithNfts = async (address) => {
  const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&showNfts=true`;

  const response = await fetch(url);
  const data = await response.json();

  console.log(`Tokens: ${data.balances.length}`);
  console.log(`NFTs: ${data.nfts?.length || 0}`);

  // Display NFTs
  data.nfts?.forEach(nft => {
    console.log(`NFT: ${nft.name || 'Unnamed'} (${nft.collectionName || 'Unknown Collection'})`);
  });

  return data;
};

getWalletWithNfts("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY");

def get_wallet_with_nfts(address: str):
    url = f"https://api.helius.xyz/v1/wallet/{address}/balances"
    params = {
        "api-key": "YOUR_API_KEY",
        "showNfts": "true"
    }

    response = requests.get(url, params=params)
    response.raise_for_status()

    data = response.json()

    print(f"Tokens: {len(data['balances'])}")
    print(f"NFTs: {len(data.get('nfts', []))}")

    # Display NFTs
    for nft in data.get('nfts', []):
        name = nft.get('name', 'Unnamed')
        collection = nft.get('collectionName', 'Unknown Collection')
        print(f"NFT: {name} ({collection})")

    return data

get_wallet_with_nfts("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY")

Filter hasil

Gunakan parameter kueri untuk mempersempit hasil yang dikembalikan:

// Only show tokens with non-zero balances
const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&showZeroBalance=false`;

// Exclude native SOL from results
const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&showNative=false`;

// Get only the top 50 tokens by value
const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&limit=50`;

Parameter kueri

Parameter	Tipe	Bawaan	Deskripsi
`page`	integer	1	Nomor halaman untuk paginasi (dimulai dari 1)
`limit`	integer	100	Jumlah maksimum token per halaman (1-100)
`showZeroBalance`	boolean	false	Sertakan token dengan saldo nol
`showNative`	boolean	true	Sertakan SOL native dalam hasil
`showNfts`	boolean	false	Sertakan NFT dalam hasil (maks. 100, hanya halaman pertama)

Format respons

{
  "balances": [
    {
      "mint": "So11111111111111111111111111111111111111111",
      "symbol": "SOL",
      "name": "Solana",
      "balance": 1.5,
      "decimals": 9,
      "pricePerToken": 145.32,
      "usdValue": 217.98,
      "logoUri": "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/So11111111111111111111111111111111111111112/logo.png",
      "tokenProgram": "spl-token"
    },
    {
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "symbol": "USDC",
      "name": "USD Coin",
      "balance": 1000.5,
      "decimals": 6,
      "pricePerToken": 1.0,
      "usdValue": 1000.5,
      "logoUri": "https://example.com/usdc-logo.png",
      "tokenProgram": "spl-token"
    }
  ],
  "nfts": [
    {
      "mint": "7Xq8wXyXVqfBPPqVJjPDwG9zN5wCVxBYZ6z7vPYBzr6F",
      "name": "Degen Ape #1234",
      "imageUri": "https://example.com/nft.png",
      "collectionName": "Degen Ape Academy",
      "collectionAddress": "DegN1dXmU2uYa4n7U9qTh7YNYpK4u8L9qXx7XqYqJfGH",
      "compressed": false
    }
  ],
  "totalUsdValue": 1218.48,
  "pagination": {
    "page": 1,
    "limit": 100,
    "hasMore": true
  }
}

Catatan kolom

balance: jumlah yang mudah dibaca manusia dan sudah disesuaikan dengan desimal — 1.5 berarti 1,5 SOL dan 1000.5 berarti 1000,5 USDC. Konversi lamport tidak diperlukan. Endpoint ini tidak menyediakan kolom mentah amountRaw; jika Anda memerlukan nilai integer yang tepat, hitung nilainya sebagai Math.round(balance * 10 ** decimals).
decimals: disediakan hanya sebagai referensi.
pricePerToken / usdValue: bernilai null untuk token tanpa data harga DAS (lihat catatan harga di atas).
totalUsdValue: total nilai USD hanya untuk halaman respons saat ini. Untuk mendapatkan nilai seluruh portofolio, telusuri semua halaman dan jumlahkan usdValue dari setiap saldo.
tokenProgram: standar token yang digunakan setiap token — spl-token (SPL Token lama) atau token-2022 (Token Extensions). Keduanya didukung sepenuhnya.

Kasus penggunaan

Membuat dasbor portofolio

Tampilkan kepemilikan pengguna beserta nilai USD:

const renderPortfolio = async (address) => {
  const { balances, totalUsdValue } = await getWalletBalances(address);

  console.log(`Current Page Value: $${totalUsdValue.toLocaleString()}`);
  console.log(`\nTop Holdings:`);

  // totalUsdValue is page-scoped; paginate before computing full portfolio value.
  balances.slice(0, 10).forEach((token, i) => {
    if (token.usdValue) {
      console.log(`${i + 1}. ${token.symbol}: ${token.balance.toFixed(4)} ($${token.usdValue.toFixed(2)})`);
    }
  });
};

Menghitung konsentrasi token

Analisis diversifikasi portofolio:

const analyzeConcentration = async (address) => {
  const { balances, totalUsdValue } = await getWalletBalances(address);

  const tokensWithValue = balances.filter(t => t.usdValue);

  if (tokensWithValue.length === 0) {
    console.log('No tokens with USD pricing data available');
    return null;
  }

  const topToken = tokensWithValue[0];
  const pageConcentration = (topToken.usdValue / totalUsdValue) * 100;

  console.log(`Largest Position on Current Page: ${topToken.symbol} (${pageConcentration.toFixed(1)}%)`);

  if (pageConcentration > 50) {
    console.log(`Warning: Current page is highly concentrated in ${topToken.symbol}`);
  }

  return { topToken, pageConcentration };
};

Melacak saldo token tertentu

Pantau token tertentu di beberapa dompet:

const getTokenBalance = async (address, tokenMint) => {
  const { balances } = await getWalletBalances(address);

  const token = balances.find(t => t.mint === tokenMint);

  if (!token) {
    console.log(`Token not found in wallet`);
    return null;
  }

  console.log(`${token.symbol} Balance: ${token.balance}`);
  console.log(`USD Value: $${token.usdValue || 'N/A'}`);

  return token;
};

// Example: Check USDC balance
getTokenBalance(
  "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
  "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" // USDC mint
);

Mengekspor kepemilikan untuk pelaporan pajak

Buat rekam kondisi kepemilikan:

const exportHoldingsSnapshot = async (address) => {
  const { balances, totalUsdValue } = await getWalletBalances(address);

  const snapshot = {
    date: new Date().toISOString(),
    address,
    pageValueUSD: totalUsdValue,
    holdings: balances
      .filter(t => t.usdValue)
      .map(t => ({
        symbol: t.symbol,
        mint: t.mint,
        balance: t.balance,
        pricePerToken: t.pricePerToken,
        usdValue: t.usdValue
      }))
  };

  console.log(JSON.stringify(snapshot, null, 2));
  return snapshot;
};

Paginasi

Untuk dompet yang memiliki lebih dari 100 token, telusuri hasil per halaman menggunakan parameter page dan pagination.hasMore:

const getAllBalances = async (address) => {
  let allBalances = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&page=${page}&limit=100`;

    const response = await fetch(url);
    const data = await response.json();

    allBalances = allBalances.concat(data.balances);
    hasMore = data.pagination.hasMore;
    page++;

    console.log(`Fetched page ${data.pagination.page}, total tokens so far: ${allBalances.length}`);
  }

  console.log(`Total tokens: ${allBalances.length}`);
  return allBalances;
};

NFT hanya dikembalikan pada halaman pertama (hingga 100), terlepas dari paginasi token.

Praktik terbaik

Filter saldo nol agar antarmuka lebih bersih. Gunakan showZeroBalance=false untuk menyembunyikan token yang tidak lagi dimiliki dompet.
Sertakan NFT hanya saat diperlukan. Secara bawaan, NFT dikecualikan demi performa; atur showNfts=true hanya saat menampilkannya.
Tangani data harga yang tidak tersedia. Selalu periksa apakah pricePerToken dan usdValue bernilai null sebelum menampilkannya. Nilai ini merupakan estimasi per jam dari DAS, bukan harga pasar waktu nyata.
Cache respons. Data saldo dapat disimpan dalam cache selama beberapa detik untuk mengurangi panggilan API.
Terapkan paginasi untuk dompet besar. Beberapa dompet memiliki ribuan token; terapkan paginasi untuk menanganinya secara efisien.

Kesalahan umum

Kode Kesalahan	Deskripsi	Solusi
400	Format alamat dompet tidak valid	Pastikan alamat tersebut merupakan alamat Solana base58 yang valid
401	Kunci API tidak ada atau tidak valid	Pastikan kunci API Anda disertakan dalam permintaan
429	Batas laju terlampaui	Kurangi frekuensi permintaan atau tingkatkan paket Anda

Langkah berikutnya

Historical Balance

Dapatkan saldo token atau SOL pada stempel waktu, tanggal dan waktu, atau slot sebelumnya.

Wallet API Overview

Semua endpoint Wallet API dan konvensi bersama.

API Reference

Skema permintaan dan respons untuk saldo dompet.

Memulai

Streaming Data & Pemantauan Peristiwa

API Data & RPC

Perdagangan

Mengirim Transaksi

Dompet sebagai Layanan

Privasi

Sumber Daya

Cara Mendapatkan Saldo Dompet

Ikhtisar

Kapan menggunakannya

Mulai cepat

Kueri saldo dasar

Sertakan NFT dalam hasil

Filter hasil

Parameter kueri

Format respons

Catatan kolom

Kasus penggunaan

Membuat dasbor portofolio

Menghitung konsentrasi token

Melacak saldo token tertentu

Mengekspor kepemilikan untuk pelaporan pajak

Paginasi

Praktik terbaik

Kesalahan umum

Langkah berikutnya

Historical Balance

Wallet API Overview

API Reference

​Ikhtisar

​Kapan menggunakannya

​Mulai cepat

​Kueri saldo dasar

​Sertakan NFT dalam hasil

​Filter hasil

​Parameter kueri

​Format respons

​Catatan kolom

​Kasus penggunaan

​Membuat dasbor portofolio

​Menghitung konsentrasi token

​Melacak saldo token tertentu

​Mengekspor kepemilikan untuk pelaporan pajak

​Paginasi

​Praktik terbaik

​Kesalahan umum

​Langkah berikutnya

Historical Balance

Wallet API Overview

API Reference

Ikhtisar

Kapan menggunakannya

Mulai cepat

Kueri saldo dasar

Sertakan NFT dalam hasil

Filter hasil

Parameter kueri

Format respons

Catatan kolom

Kasus penggunaan

Membuat dasbor portofolio

Menghitung konsentrasi token

Melacak saldo token tertentu

Mengekspor kepemilikan untuk pelaporan pajak

Paginasi

Praktik terbaik

Kesalahan umum

Langkah berikutnya