Splash API
Public wallet balances, DeFi positions and portfolio totals. Look up an address or name. No API key required.
https://splash.dudidum.com1. Get a portfolio
Start here for wallet balances, supported protocol positions and Hyperliquid equity in one response. Replace the address with your own, an .eth name or an .hl name.
/v1/explorer/addresses/{address}curl --fail-with-body \ 'https://splash.dudidum.com/v1/explorer/addresses/0xbdfa4f4492dd7b7cf211209c4791af8d52bf5c50'
const address = '0xbdfa4f4492dd7b7cf211209c4791af8d52bf5c50';
const response = await fetch(
'https://splash.dudidum.com/v1/explorer/addresses/' + address
);
const data = await response.json().catch(() => null);
if (!response.ok) throw new Error(data?.error?.message ?? 'Lookup unavailable');
if (!data) throw new Error('No portfolio response');
console.log(data.summary.totalValueUsd); // null if the total is incomplete
console.log(data.summary.knownValueUsd); // known subtotal, not a complete totalUse these public lookups from your server or browser. Cross-origin browser requests are supported without credentials.
No sign-up, API key or authentication header is required. An optional AccessKey value is accepted but is not validated and does not grant extra access. Pass each query parameter once.
2. Read the result
| Field | Meaning |
|---|---|
address | The resolved EVM address. Names never replace this field. |
complete | Whether the covered checks succeeded, not whether every possible asset was discovered. |
summary.totalValueUsd | Portfolio total, or null when incomplete. |
summary.knownValueUsd | Known subtotal, retained when the full total is unavailable. |
summary.walletUsd | Wallet token value, or null when incomplete. |
summary.positionsNetUsd | Net protocol positions and Hyperliquid equity. Debt is already deducted. |
summary.debtUsd / debtComplete | Known borrowing in USD. Only debtComplete: true confirms the covered borrowing checks and prices succeeded; otherwise this is a subtotal, even when zero. debtMissing explains gaps. Unrelated wallet or supply-only failures do not invalidate a successful borrowing check. |
evm.wallet.tokens | Wallet tokens, quantities, prices and values. |
evm.wallet.spamTokens | Separately flagged spam, excluded from normal tokens and totals. Prices and values stay null. |
evm.protocols / defi.positions | Aave/Compound positions and additional protocol positions. |
hyperliquid | Hyperliquid equity and positions for this address. |
sources / summary.missing | Check statuses and reasons a value is incomplete. HTTP 200 can still contain partial data. |
fetchedAt / cache | Observation time and cache status. Cache hits do not change the observation time. |
Summary USD totals and raw wallet quantities are decimal strings. Keep their full precision when calculating. null means unknown; "0" means an observed zero. Token discovery is bounded, not exhaustive. See coverage for supported chains.
Prices may represent market estimates, reference prices or underlying-asset value, not guaranteed sale proceeds. Hyperliquid outcome holdings include kind: "outcome", outcome and side in their token metadata. A settled claim can correctly have a zero price.
For compressed responses, use curl --compressed or your HTTP client's compression support. JSON fields and values are unchanged.
An incomplete response keeps its known subtotal and leaves the full total unknown:
{
"complete": false,
"summary": {
"totalValueUsd": null,
"knownValueUsd": "160"
}
}Portfolio value is wallet value plus protocol assets minus debt plus Hyperliquid equity. Wallet tokens already represented by protocol positions are excluded from the combined wallet value. Gross perpetual exposure is separate. Hyperliquid equity uses the USDC=$1 estimate; other wallet stablecoins are not assumed to equal one dollar.
Cache and refresh
Portfolio lookups use the same flow as the web interface. Splash makes a best-efforts lookup for any valid address. If portfolio data is already available, it can be returned immediately; otherwise, allow a few moments for the lookup to populate.
If a lookup returns an older estimate during an update, it remains partial with cache.state: "stale" and summary.totalValueUsd: null. A failed update never makes an older estimate complete.
Add ?refresh=true to request fresh checks across supported portfolio areas. Results less than 15 seconds old are reused. Read cache.state and fetchedAt for status and the latest observation attempt. Reusing a result does not change its observation time. If a check fails, earlier values may be retained with incomplete totals. Retained tokens carry retained: true and their original observedAt; retained positions keep their original updateAt. A source with retained data has retained: true and retainedObservedAt.
Unpriced and spam tokens
Wallet observations keep flagged spam separately in wallet.spamTokens (evm.wallet.spamTokens in unified responses), excluded from portfolio totals. Their quantities remain available, with null prices and values. Ordinary tokens without reliable prices stay in tokens and keep the total partial; unpriced does not mean spam.
An explicit /v1/user/token request can still return a flagged token's quantity. Its zero compatibility price is not a verified valuation; check X-Splash-Valuation.
Exact-address scope
Unified lookups combine the supplied address's EVM assets with its Hyperliquid account and officially linked Hyperliquid subaccounts. Each Hyperliquid account is returned separately. Trading agents are not resolved to their owners. Verified sole-owner Polymarket Safe prediction claims can also be included, but not the Safe's cash or unrelated positions. Address-only compatibility endpoints keep their existing scope.
Choose a narrower lookup
All address paths accept an EVM address, .eth name or .hl name. Use chain and protocol IDs from supported protocols.
| GET endpoint | Returns | Optional query |
|---|---|---|
/v1/explorer/addresses/{address} | Combined wallet, supported protocols and Hyperliquid equity. | refresh=true|false |
/v1/defi/addresses/{address} | Additional protocols, excluding Aave/Compound and Hyperliquid accounts. | chain_ids, protocol_id |
/v1/portfolio/addresses/{address} | Wallet balances plus Aave/Compound only. | chain_ids |
/v1/lending/addresses/{address} | Aave/Compound supplies, debt and covered rewards, including accrued Compound V2 COMP. No wallet balances. | chain_ids, protocol_id |
/v1/addresses/{address} | Hyperliquid portfolio and checked recent activity. Trading agents resolve to their trading account. | includeSubaccounts=true|false, default true |
chain_ids is comma-separated, for example eth,base. protocol_id selects one chain-specific protocol, for example morphoblue or arb_fluid. Unsupported parameters return 400. The unified lookup does not accept chain or protocol filters.
Hyperliquid activity is recent checked activity, not a lifetime history. An empty history does not prove lifetime inactivity. See lookup and refresh behavior above.
Portfolio and token endpoints
These endpoints take a hex wallet address in id, not an ENS or HL name. Responses are unwrapped arrays or objects with JSON-number amounts. For exact raw quantities, use evm.wallet.tokens[].rawAmount in the unified lookup rather than numeric raw_amount.
curl --fail-with-body \ 'https://splash.dudidum.com/v1/user/token_list?id=0xbdfa4f4492dd7b7cf211209c4791af8d52bf5c50&chain_id=eth'
| GET endpoint | Required query | Returns |
|---|---|---|
/v1/chain/list | None | Supported EVM chains. |
/v1/chain | id | One chain's metadata. |
/v1/protocol | id | One protocol's metadata. |
/v1/protocol/all_list | None | Supported protocols. Optional chain_ids. |
/v1/protocol/list | chain_id | Protocols on one chain. |
/v1/user/total_balance | id | Wallet and net protocol value plus Hyperliquid equity. chain_list contains EVM subtotals. |
/v1/user/all_complex_protocol_list | id | Protocol positions. Optional chain_ids. |
/v1/user/complex_protocol_list | id, chain_id | Protocol positions on one chain. |
/v1/user/all_simple_protocol_list | id | Protocol value summaries. Optional chain_ids. |
/v1/user/simple_protocol_list | id, chain_id | Protocol value summaries on one chain. |
/v1/user/protocol | id, protocol_id | Positions in one chain-specific protocol. |
/v1/user/all_token_list | id | Covered wallet tokens. Optional chain_ids, is_all. |
/v1/user/token_list | id, chain_id | Covered tokens on one chain. Optional is_all. |
/v1/user/token | id, chain_id, token_id | One wallet token. |
/v1/token | id, chain_id | Token metadata and price. Here id is a token ID. |
/v1/token/list_by_ids | ids, chain_id | Metadata for up to 100 comma-separated token IDs. |
/v1/user/used_chain_list | id | Chains with observed covered holdings. |
/v1/user/chain_balance | id, chain_id | One chain's net wallet and protocol value. |
/v1/app_protocol/list | None | Hyperliquid app metadata. |
/v1/user/complex_app_list | id | Hyperliquid app positions, separate from EVM protocols. |
These routes allow cross-origin browser requests and optional AccessKey headers. Failed covered sources return 503 rather than an empty portfolio. Missing prices may be 0; inspect X-Splash-Valuation: partial-priced-subtotal. Token lists default to is_all=true; false returns core tokens only. It does not expand discovery or include quarantined spam. Send each query parameter once.
NFT lists support Ethereum and Optimism. For exact quantities and pagination, use the NFT gallery endpoint. Unsupported lists, such as approvals and value history, return []. Unsupported object endpoints return an empty object of the documented shape. Check X-Splash-Coverage: empty-unsupported; this does not mean the wallet is empty. Transaction pre-execution returns success:false. The OpenAPI specification lists every endpoint and response shape.
Bring your existing client
Our API is compatible with DeBank's portfolio and token request format. If you're familiar with them, welcome home.
- Change the API root to
https://splash.dudidum.com. - Keep your request paths and parameters for the portfolio and token endpoints listed above.
- Keep your
AccessKeyheader or leave it out. Any value is accepted.
Compatibility covers the listed paths, methods, query names and unwrapped response shapes.
Splash provides portfolio data on a best-efforts basis and does not warrant or guarantee that all tokens, protocols or positions will be identified, supported or valued, including, without limitation, wallet balances, lending and borrowing positions, staking, liquidity pools and vault holdings. Coverage, prices and update times may vary, and reported portfolio values may differ from those of other services.
Unsupported features keep their documented empty shape, not a successful financial or transaction check. Use the full endpoint reference for availability. Your first request can be the token-list example.
Resolve names
/v1/resolve/{identifier}Accepts a hex address, .eth name or .hl name, including subnames. Returns address, normalized name and kind. Names resolve to their current target address, not the name owner. Forward results are reused for at most 60 seconds. Missing names return 404; unavailable lookups return 503. Neither starts a portfolio lookup.
/v1/identity/{identifier}Returns displayName, names and status. HL primary names take precedence, followed by confirmed HL aliases, ENS primary names, ENS aliases and the address. Both name systems are returned when present. partial or unavailable means discovery was incomplete, not that no name exists.
Display names can be reused independently for up to one hour, capped by known ENS registration or subname expiry. ENS without expiry information is reused for at most 60 seconds. Read each name's cacheExpiresAt and ttlSeconds; registrationExpiresAt is optional expiry information, not a guarantee that records cannot change sooner.
These endpoints accept no query parameters. Address lookups add identity when the input is a name; financial address fields stay hex addresses.
Identity responses also include referenceRank, an optional last-recorded external social rank with its observation time and source URL. It is independent of portfolio value.
Wallet identity also includes entity: a known exchange attribution with category: "cex", id, name, chains and sources. A null entity means no known attribution, not proof of a personal wallet. Exchange labels do not replace ENS/HL names or change balances.
NFTs & Profile Pictures
/v1/nft/addresses/{address}Get ERC-721 and ERC-1155 holdings for an address, .eth or .hl name. Set chain_id=eth (default) or chain_id=op. Add is_all=true to include collections outside the default trusted set.
curl --fail-with-body \ 'https://splash.dudidum.com/v1/nft/addresses/vitalik.eth?chain_id=eth'
Read items, then pass nextCursor back as cursor with the same address and filters until it is null. Each page checks up to 50 candidates, with no fixed page-count limit. Cursors last up to one hour; if one expires, start again without a cursor. complete=false means more pages or incomplete checks. Results may be reused for five minutes. Token IDs and amounts are exact strings. Non-null imageUrl values are Splash-relative paths, such as /v1/nft/images/{id}; resolve them against the API base URL. marketplaceUrl is a separate external marketplace link. NFT prices are not included in portfolio totals.
The /v1/user/nft_list and /v1/user/all_nft_list routes return the first page for supported requested chains. Check X-Splash-Coverage: partial-nft-discovery before treating a list as complete.
Wallet identity responses may include avatarUrl for a confirmed primary ENS profile picture. Use it as an image URL; retain a fallback when the image is unavailable. NFT images use each item's imageUrl.
Get the leaderboard
/v1/leaderboardWallets queried through portfolio endpoints join automatically. Names that resolve to the same address share one entry. Results are always ranked by cached USD net value, highest first. Unobserved values come last.
curl --fail-with-body \ 'https://splash.dudidum.com/v1/leaderboard?q=alice.eth&page=1'
Both query parameters are optional. q searches known names, addresses, exchange labels or protocols, ignoring case (maximum 512 characters). page starts at 1; each page contains up to 20 wallets. A page beyond the end returns the last available page. Other query parameters return 400.
{
"version": 3,
"page": 1,
"pageSize": 20,
"pageCount": 1,
"totalEntries": 1,
"matchedEntries": 1,
"entries": [{
"rank": 1,
"address": "0x1111111111111111111111111111111111111111",
"netWorthUsd": "160",
"valuationComplete": true,
"stale": false,
"refreshFailed": false
}]
}| Field | Meaning |
|---|---|
entries | The requested page. An unmatched search returns []. |
totalEntries / matchedEntries | All listed wallets and wallets matching your search. Use page and pageCount to navigate. |
rank | The wallet's position across the whole leaderboard, even in search results. Equal values use address order. |
referenceRank | An optional last-recorded external social rank, with rank, observedAt, ranking and sourceUrl. Independent of net value and list order. null means no rank is recorded, not that the wallet is unranked. |
netWorthUsd | Exact USD decimal string. Debt is already deducted. Can be negative; null means not yet observed. |
valuationComplete | When false, the value is a known subtotal or an older estimate, not a complete current total. |
valueObservedAt / stale | Original observation time and whether it has reached this wallet's freshness window. Observation time is null before the first value. |
refreshEverySeconds | On an entry: its current window, 3600 or 14400. The top-level field is the most frequent update target; refreshPolicy summarizes the windows. |
refreshFailed | The latest leaderboard update failed. Any previous value is retained. |
protocols | Each item has family, name and signed decimal-string netValueUsd. Values add up to the same portfolio subtotal. |
Wallet requests retain their resolved address in the leaderboard, including addresses whose first value is not available yet. Available values appear immediately; wallets without a value remain pending until a lookup succeeds. Check each entry's observation time and status. Reading the leaderboard does not request new portfolio data. All amounts stay in USD, regardless of your preferred display currency.
/v1/leaderboard/identitiesUse the same q and page to get names for that page without balances. Read names and status as described under Resolve names. The leaderboard interface displays ENS first with HL alongside.
/v1/leaderboard/identities/streamFor names as they arrive, use EventSource or curl -N with the same filters. Each identity event contains one identity object; replace the previous result for that address. ENS and HL may arrive separately. pending means discovery is running, not that a name is missing. Close on done. On an error or disconnect, keep received names, close the connection and retry later. Connections last up to 150 seconds. Ranks and portfolio values are unchanged.
Other useful endpoints
| GET endpoint | Returns |
|---|---|
/health | Splash availability. status:"ok" does not guarantee every portfolio source is available. |
Portfolio amounts are returned in USD. Use /v1/chain/list to discover supported chains and /v1/protocol/all_list for protocol IDs.
Handle errors
| Status | Action |
|---|---|
200 | Read the response and check completeness; partial results are possible. |
400 | Correct the address, name, query or JSON body. |
404 | Name, route or resource not found. |
405 | Use the method listed for the endpoint. |
406 | Allow br, gzip or identity in Accept-Encoding. |
413 | Reduce the JSON body below 64 KiB. |
415 | Send Content-Type: application/json for POST requests. |
429 | Wait the number of seconds in Retry-After before retrying. |
503 | Data or capacity is temporarily unavailable. Retry with backoff; do not treat it as an empty wallet. |
500 | Unexpected service error. Retry later. |
Address errors use {"error":{"code":"...","message":"..."}}. Portfolio and token routes use {"error_code":400,"error_msg":"..."}. A failed lookup can instead return a lookup-shaped response with source errors; check the HTTP status before using any total.
Check the HTTP status before parsing JSON. Transport errors can have an empty body: 406 means no acceptable response encoding; 503 means retry later. Follow Retry-After when present.
The public request budget replenishes at 120 requests per minute per network client, with bursts of 30 and up to 8 concurrent requests. Image requests have a separate budget. Shared service capacity can also limit requests. Read X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; reset is the number of seconds until the burst budget is full. Limits apply independently of AccessKey. On 429, follow Retry-After, avoid parallel retries and use backoff. Public API routes support cross-origin browser requests without credentials.
Supported protocols and chains
Use these IDs in the matching endpoint's filters. Support covers available position types, not every product offered by a protocol. Use /v1/chain/list and /v1/protocol/all_list for discovery.
Additional protocols
| Protocol | Chain IDs | Protocol IDs |
|---|---|---|
| Merkl | eth | merkl |
| Ethena | eth | ethena |
| Venzo | arb | arb_venzofinance |
| Ethos | base | base_ethosnetwork |
| infiniFi | eth | infinifixyz |
| ether.fi | eth | etherfi |
| 3Jane | eth | threejane |
| Theo | eth | theo |
| Accountable | monad | monad_accountable |
| Apyx | eth | apyxfi |
| Rysk | hyper | hyper_rysk |
| Yearn V2 | eth | yearn2 |
| Curve | eth | curve |
| Symbiotic | eth | symbiotic |
| EigenLayer | eth | eigenlayer |
| Blur | eth | blur |
| Alchemix V3 | eth, op, arb, base | alchemix3, op_alchemix3, arb_alchemix3, base_alchemix3 |
| Contango | eth, op, base, arb | contango, op_contango, base_contango, arb_contango |
| Aster | bsc | bsc_astherus |
| Papertrade | hyper | hyper_papertrade |
| Aerodrome | base | base_aerodrome |
| Polygon Staking | eth | polygon_staking |
| Upshift | eth, bsc, base, hyper, monad, avax | upshift, bsc_upshift, base_upshift, hyper_upshift, monad_upshift, avax_upshift |
| Dolomite | eth, base, bera, arb, mnt, xlayer | dolomite, base_dolomite, bera_dolomite, arb_dolomite, mnt_dolomite, xlayer_dolomite |
| Uniswap V3 | eth, op, matic, arb, base, bsc, avax | uniswap3, op_uniswap3, matic_uniswap3, arb_uniswap3, base_uniswap3, bsc_uniswap3, avax_uniswap3 |
| Uniswap V2 | eth, op, base, arb | uniswap2, op_uniswap2, base_uniswap2, arb_uniswap2 |
| Uniswap V4 | eth, op, base, arb | uniswap4, op_uniswap4, base_uniswap4, arb_uniswap4 |
| Morpho | eth, base, katana, hyper, arb, matic, uni, op, world, monad, tempo, hood | morphoblue, base_morphoblue, katana_morphoblue, hyper_morphoblue, arb_morphoblue, matic_morphoblue, uni_morphoblue, op_morphoblue, world_morphoblue, monad_morphoblue, tempo_morphoblue, hood_morphoblue |
| Fluid | eth, arb, base, matic, plasma | fluid, arb_fluid, base_fluid, matic_fluid, plasma_fluid |
| Polymarket | matic | matic_polymarket |
| HyperLend | hyper | hyper_hyperlend |
| Kinetiq | hyper | hyper_kinetiq |
| Pendle V2 | eth, bsc, monad, xlayer, hyper, base, plasma, arb, op, sonic, mnt | pendle2, bsc_pendle2, monad_pendle2, xlayer_pendle2, hyper_pendle2, base_pendle2, plasma_pendle2, arb_pendle2, op_pendle2, sonic_pendle2, mnt_pendle2 |
| MegaETH | megaeth | megaeth_megaethcom |
Aave and Compound markets
| Chain / ID | Markets | Protocol IDs |
|---|---|---|
Ethereum eth | 31 | aave3, aave, aave4, aave2, compound3, compound |
OP op | 4 | op_aave3, op_compound3 |
BNB Chain bsc | 1 | bsc_aave3 |
Gnosis Chain xdai | 1 | xdai_aave3 |
Unichain uni | 2 | uni_compound3 |
Polygon matic | 4 | matic_aave3, matic_aave2, matic_compound3 |
Monad monad | 1 | monad_aave3 |
Sonic sonic | 1 | sonic_aave3 |
X Layer xlayer | 1 | xlayer_aave3 |
zkSync Era era | 1 | era_aave3 |
Metis metis | 1 | metis_aave3 |
Soneium soneium | 1 | soneium_aave3 |
Ronin ron | 2 | ron_compound3 |
MegaETH megaeth | 1 | megaeth_aave3 |
Mantle mnt | 2 | mnt_aave3, mnt_compound3 |
Arc arc | 3 | arc_aave4 |
Base base | 7 | base_aave3, base_aave4, base_compound3 |
Plasma plasma | 1 | plasma_aave3 |
Arbitrum arb | 5 | arb_aave3, arb_compound3 |
Celo celo | 1 | celo_aave3 |
Avalanche avax | 6 | avax_aave3, avax_aave4, avax_aave2 |
Ink ink | 1 | ink_aave3 |
Linea linea | 3 | linea_aave3, linea_compound3 |
Scroll scrl | 2 | scrl_aave3, scrl_compound3 |