Skip to main content

Wallet Balances

Query token balances, NFTs, and portfolio value for any address.

Try it Live

Open in Swagger UI → to test these endpoints interactively.

Endpoints​

EndpointDescriptionPrice
GET /api/wallet/{address}/balancesToken balances$0.01
GET /api/wallet/{address}/nftsNFT holdings$0.02
GET /api/wallet/{address}/portfolioFull portfolio$0.02
GET /api/wallet/{address}/transactionsRecent transactions$0.01

GET /api/wallet/{address}/balances​

Get ERC-20 token balances for a wallet.

Query Parameters​

ParamTypeDefaultDescription
chainstringethereumChain to query
minValuenumber0Min USD value to include

Request​

curl "https://api.web3identity.com/api/wallet/0xd8dA.../balances?chain=ethereum"

Response​

{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "chain": "ethereum",
  "tokens": [
    {
      "symbol": "ETH",
      "name": "Ethereum",
      "balance": "1234.567",
      "decimals": 18,
      "price": 3245.67,
      "value": 4007890.45,
      "contract": null
    },
    {
      "symbol": "USDC",
      "name": "USD Coin",
      "balance": "50000.00",
      "decimals": 6,
      "price": 1.0,
      "value": 50000.00,
      "contract": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
    }
  ],
  "totalValue": 4057890.45,
  "count": 15
}

SDK​

const balances = await client.getBalances('0xd8dA...');
console.log(balances.totalValue); // 4057890.45

GET /api/wallet/{address}/nfts​

Get NFT holdings.

Query Parameters​

ParamTypeDefaultDescription
chainstringethereumChain to query
limitnumber50Max results

Response​

{
  "address": "0xd8dA...",
  "nfts": [
    {
      "contract": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
      "collection": "Bored Ape Yacht Club",
      "tokenId": "1234",
      "name": "BAYC #1234",
      "image": "ipfs://...",
      "floorPrice": 25.5
    }
  ],
  "count": 42,
  "estimatedValue": 156000
}

GET /api/wallet/{address}/portfolio​

Complete portfolio including tokens, NFTs, DeFi positions.

Response​

{
  "address": "0xd8dA...",
  "summary": {
    "totalValue": 5234567.89,
    "tokens": 4057890.45,
    "nfts": 156000,
    "defi": 1020677.44
  },
  "tokens": [...],
  "nfts": [...],
  "defi": [
    {
      "protocol": "Aave",
      "type": "lending",
      "supplied": 500000,
      "borrowed": 0,
      "healthFactor": 2.5
    }
  ]
}

GET /api/wallet/{address}/transactions​

Recent transactions.

Query Parameters​

ParamTypeDefaultDescription
chainstringethereumChain
limitnumber20Max results

Response​

{
  "transactions": [
    {
      "hash": "0x...",
      "block": 19234567,
      "timestamp": "2026-02-08T04:30:00Z",
      "from": "0xd8dA...",
      "to": "0x...",
      "value": "1.5",
      "gasUsed": 21000,
      "status": "success"
    }
  ],
  "count": 20
}

Supported Chains​

ChainIDStatus
Ethereum1✅
Base8453✅
Arbitrum42161✅
Optimism10✅
Polygon137✅

SDK Examples​

JavaScript​

import { Web3IdentityClient } from '@web3identity/sdk';

const client = new Web3IdentityClient();

// Get token balances
const balances = await client.getBalances('vitalik.eth', {
  chain: 'ethereum',
  minValue: 100
});

console.log(`Total value: $${balances.totalValue.toLocaleString()}`);

// Get NFTs
const nfts = await client.getNFTs('vitalik.eth');
console.log(`NFT count: ${nfts.count}`);

// Full portfolio with DeFi positions
const portfolio = await client.getPortfolio('vitalik.eth');
console.log(`DeFi TVL: $${portfolio.summary.defi.toLocaleString()}`);

Python​

from web3identity import Client

client = Client()

# Get balances for ENS name
balances = client.get_balances('vitalik.eth', chain='ethereum')
print(f"Total: ${balances['totalValue']:,.2f}")

# Get portfolio
portfolio = client.get_portfolio('vitalik.eth')
for token in portfolio['tokens'][:5]:
    print(f"{token['symbol']}: ${token['value']:,.2f}")

cURL Examples​

# Get Ethereum balances
curl "https://api.web3identity.com/api/wallet/0xd8dA.../balances?chain=ethereum"

# Get Base chain balances only above $10
curl "https://api.web3identity.com/api/wallet/0xd8dA.../balances?chain=base&minValue=10"

# Get NFTs
curl "https://api.web3identity.com/api/wallet/0xd8dA.../nfts?limit=20"

# Full portfolio
curl "https://api.web3identity.com/api/wallet/0xd8dA.../portfolio"