Getting started
Indexed data
For production, feed 0xui from an index of the chain, either your own (Postgres + ClickHouse) or a service like Goldsky.
Out of the box, 0xui components read straight from the chain over RPC. That needs zero setup and suits prototypes, small token lists and single users. In production it hits limits:
| Reading over RPC | What goes wrong |
|---|---|
| Balances for a 400-token list | Dozens of eth_call batches per user, and public RPCs rate-limit you. |
Event history (historyBlocks) |
Providers cap eth_getLogs ranges, so you only see recent blocks. |
| Transaction history | Only what this browser recorded: per device, and nothing from other apps. |
| Portfolios across chains | One set of reads per chain, per user, per page view. |
| Spam tokens | RPC can’t tell a real USDC from a copy. Portfolio hides the obvious ones; verdicts for the rest need a scanner. |
We recommend putting an index of the chain behind your app and passing its data into the components. Every data-heavy component accepts it through a prop and then skips its RPC reads.
Plugging in your data
Section titled “Plugging in your data”| Component | Prop | Your index provides |
|---|---|---|
| Token Select | balances |
The account’s balance per token address |
| Portfolio | balances |
The same, for every token in the list |
| Portfolio | holdings |
Every token the account holds, with its own metadata. Off-list tokens need showUnlisted |
| Transaction History | transactions |
The account’s transactions, from any device or app |
| Event Feed | initialEvents |
Past events. New ones still stream in over RPC. |
useTokenList |
allowlist / blocklist |
Tokens you’ve verified, or flagged as spam |
| Portfolio | isSpam |
Spam verdicts from a scanning service or your own rules |
function Holdings({ address }: { address: Address }) { const { tokens } = useTokenList(UNISWAP_DEFAULT_LIST); const { data } = useQuery({ queryKey: ["balances", address], queryFn: async () => { const rows: { token: string; balance: string }[] = await fetch(`/api/balances/${address}`).then((r) => r.json()); // bigints travel as strings over JSON return Object.fromEntries(rows.map((r) => [r.token, BigInt(r.balance)])); }, }); return <Portfolio tokens={tokens} address={address} balances={data} prices={prices} />;}While balances is undefined (still loading), components fall back to reading over RPC. Pass {} instead if you never want RPC reads.
Option 1: run your own index (Postgres + ClickHouse)
Section titled “Option 1: run your own index (Postgres + ClickHouse)”The split that works well for chain data: Postgres for current state, ClickHouse for history.
- Postgres holds what changes in place and what you look up by key: current balances, allowances, your verified-token table, users. It’s transactional, so balance updates and reorg rollbacks stay consistent.
- ClickHouse holds what only grows: transfers, swaps, every event. It’s a columnar database built for scanning and aggregating billions of rows, which is what “history for this address” and “volume per token per day” need.
An indexer (your own service, or a framework such as Ponder or rindexer) follows new blocks, decodes the logs you care about, writes events to ClickHouse and applies their effects to Postgres. Your API serves the components.
Example tables, to adapt rather than copy:
-- Postgres: current balances, upserted by the indexercreate table token_balances ( chain_id integer not null, owner text not null, -- lowercase address token text not null, balance numeric(78, 0) not null, -- fits uint256 block bigint not null, -- last block that changed it, for reorg handling primary key (chain_id, owner, token));-- ClickHouse: every ERC-20 transfer, append-onlyCREATE TABLE transfers( chain_id UInt32, block_number UInt64, block_time DateTime, tx_hash String, log_index UInt32, token LowCardinality(String), sender String, recipient String, value UInt256)ENGINE = ReplacingMergeTreeORDER BY (chain_id, block_number, tx_hash, log_index);-- ReplacingMergeTree de-duplicates re-ingested logs (after a restart or reorg) by the ORDER BY key.-- For "transfers of this address", add a table or projection ordered by (chain_id, recipient, block_number).Option 2: use a managed indexer (Goldsky)
Section titled “Option 2: use a managed indexer (Goldsky)”If you’d rather not run ingestion yourself, Goldsky runs it for you:
- Subgraphs: describe the events you care about and query the indexed result over GraphQL. A good fit for history and feeds.
- Mirror: streams chain data (blocks, logs, transfers, decoded events) into a database you own, such as Postgres or ClickHouse, so you keep the setup from option 1 without writing the ingestion.
Either way, the shape the components need doesn’t change: balances by token address, transactions as HistoryEntry[], events as decoded logs.
When RPC is fine
Section titled “When RPC is fine”Keep the defaults for prototypes, internal tools, testnets, short token lists, and anything where one user loads one page now and then. The components are built so you can start on RPC and move to an index without changing the UI, only adding props.
