{"uid":"cap_9FCq2tOknq8rg6SnKBaO8","slug":"goldsky-feeds-wallet-token-balances-ff246023","name":"Goldsky Feeds: Wallet Token Balances","description":"Goldsky Feeds: onchain data over REST. Formerly Edge Data / Data APIs; existing URLs and keys keep working.\n\n- **Wallet feeds**: one wallet's token transfers or balances across chains, with USD values (`/feeds/wallets/transfers`, `/feeds/wallets/balances`).\n- **Tokens**: metadata and current USD price for up to 100 `chain:token_address` pairs per request (`/feeds/tokens`).\n- **Prediction markets** (Polymarket, on Polygon): Activity, Positions and Balances (`/polymarket/*`).\n- **Chain datasets**: Blocks and Chain head for each supported chain (`/blocks/{chain}`, `/blocks/{chain}/head`).\n\nBase URL: `https://edge.goldsky.com/data`. Every endpoint is a `GET` that returns JSON.\n\n## Authentication\n\nSend your Feeds API key in the `x-api-key` header, as the `?key=` query parameter, or as `Authorization: Bearer <key>`. Get it at [app.goldsky.com](https://app.goldsky.com) under **Feeds → API keys**. One key works for every endpoint; an invalid key gets `401`.\n\n## Billing\n\nRequests made with a key bill compute units (CUs) at $10 per million:\n\n- Wallet feeds and Tokens: 35 CUs per request.\n- Prediction markets and Chain datasets: 1 CU per row returned. Chain head is 1 CU per call.\n\nErrors are not billed, and a Prediction markets or Chain datasets request that returns no rows costs nothing. Rate limits are set per plan (`429` when exceeded); Goldsky support can raise them.\n\n## Pay per request with x402\n\nNo account or key needed. A request without a key gets `402` with an x402 v2 challenge in the `PAYMENT-REQUIRED` header (base64 JSON; the body carries the same challenge). Pay in USDC through Circle Gateway and retry. Each payment is a $0.005 prepaid top-up, tied to the paying wallet and shared with Edge RPC, that later requests spend down:\n\n- Wallet feeds and Tokens: $0.00035 (350 atomic USDC) per request.\n- Prediction markets and Chain datasets: $0.00001 (10 atomic USDC) per request, whatever the row count.\n\nThe payment flow is in [x402 nanopayments](https://docs.goldsky.com/edge-rpc/capabilities/x402).","url":"https://edge.goldsky.com/data/feeds/wallets/balances?utm_source=zero.xyz","method":"GET","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method"],"properties":{"type":{"type":"string","const":"http"},"method":{"enum":["GET","HEAD","DELETE"],"type":"string"},"queryParams":{"type":"object","required":["address"],"properties":{"chains":{"type":["string","null"]},"address":{"type":["string","null"]},"page_size":{"type":["integer","null"]},"page_token":{"type":["string","null"]},"include_rent":{"type":"boolean"},"token_symbol":{"type":["string","null"]},"min_value_usd":{"type":["number","null"]},"token_address":{"type":["string","null"]},"include_prices":{"type":["boolean","null"]},"include_lamports":{"type":"boolean"},"include_historical":{"type":["boolean","null"]},"include_chain_fields":{"type":"boolean"},"include_unknown_price":{"type":["boolean","null"]},"include_token_metadata":{"type":["boolean","null"]}}}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object","required":["total_value_usd","wallets","data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object","required":["address","chain","chain_family","token_address","balance_raw","block_number","block_timestamp"],"properties":{"chain":{"type":"string"},"solana":{"oneOf":[{"type":"null"},{"type":"object"}]},"address":{"type":"string"},"price_usd":{"type":["number","null"]},"value_usd":{"type":["number","null"]},"token_name":{"type":["string","null"]},"balance_raw":{"type":"string"},"block_number":{"type":"integer"},"chain_family":{"type":"string"},"token_symbol":{"type":["string","null"]},"token_address":{"type":"string"},"last_priced_at":{"type":["string","null"]},"token_decimals":{"type":["integer","null"]},"token_logo_url":{"type":["string","null"]},"block_timestamp":{"type":"string"}}}},"address":{"type":["string","null"]},"wallets":{"type":"array","items":{"type":"object","required":["address","total_value_usd"],"properties":{"address":{"type":"string"},"total_value_usd":{"type":["number","null"]}}}},"pagination":{"type":"object","required":["page_size"],"properties":{"page_size":{"type":"integer"},"next_page_token":{"type":["string","null"]},"prev_page_token":{"type":["string","null"]}}},"total_value_usd":{"type":["number","null"]}}}}}}},"responseSchema":{"type":"json","schema":{"type":"object","properties":{"data":{"type":"array"},"address":{"type":"string"},"pagination":{"type":"object"},"total_value_usd":{"type":"number"}}}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.05","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.05/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.05","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.05","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_muyFKdzXGVvQtIs3EDDNF","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.05","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns token balances across chains for a given wallet address, with optional USD pricing, metadata, and pagination","exampleAgentPrompt":"What tokens does wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 hold across all chains, including their USD values and token logos?","exampleUseCases":[{"title":"DeFi portfolio dashboard population","prompt":"Pull all token balances for wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 across every chain, include USD prices and token metadata so I can display a full portfolio breakdown."},{"title":"Filter high-value wallet holdings","prompt":"Show me all tokens in wallet 0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B that are worth at least $10 USD each, with pricing data included."},{"title":"Solana wallet token audit","prompt":"Get the token balances for Solana wallet 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM, including lamports and rent details, so I can audit what it holds."}],"resultDescription":"A JSON object containing the queried wallet address, a total_value_usd field summing all holdings, a paginated data array of token balance records (each with chain, chain_family, token_address, balance_raw, token_symbol, token_name, token_decimals, price_usd, value_usd, token_logo_url, block_number, block_timestamp, and optional Solana-specific fields), and a pagination object with page_size and next_page_token for cursor-based traversal.","failureModes":["Missing required 'address' query parameter returns a 400 validation error","Invalid or malformed wallet address returns empty data or an error","Unsupported chain identifier causes a 400 or empty result","Expired or insufficient prepaid balance (x402 payment required) returns a 402 Payment Required","Rate limiting or upstream indexer lag may cause stale or incomplete balance data","Very large wallets with many tokens may require multiple paginated requests"],"whenToPreferThis":"Use this endpoint when you need structured, multi-chain token balance data for a specific wallet address, especially when USD valuation, token metadata (logos, decimals, symbols), or Solana-specific fields (lamports, rent) are needed. Prefer it over generic RPC calls when you want normalized cross-chain data with pricing in a single REST call rather than making separate chain-specific balance queries.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-31T18:35:45.398Z","isFirstParty":false,"canonicalSlug":"goldsky-feeds-wallet-token-balances-ff246023"}