Guide

Configuration

Start with the defaults, then change only the services you need to control.

The default

tsx

<WhitehashProvider>
  <App />
</WhitehashProvider>

<WhitehashProvider> ships with production-ready defaults for mainnet, public indexers and RPCs, and IPFS gateways. Override any dependency you want to control.

Use testnets

Change mode when an address lookup should target Ghostnet, Sepolia, and Base Sepolia. Project and token identities already carry their chain explicitly.

tsx

<WhitehashProvider config={{ mode: "testnet" }}>
  <App />
</WhitehashProvider>

Use your IPFS gateway

Provide gateway roots in fallback order. If omitted, the bundled defaults remain active.

tsx

<WhitehashProvider config={{
  resolver: {
    ipfsGateways: ["https://your-gateway.example", "https://ipfs.io"],
  },
}}>
  <App />
</WhitehashProvider>

Render onchfs artwork

onchfs is the only intentionally disabled capability because browsers need a service worker or HTTP proxy to load its custom URI scheme. Follow the onchfs guide to enable it.

All defaults

Setting	Default	What it controls
`mode`	`"mainnet"`	Wallet lookups use Tezos mainnet, Ethereum, and Base
`resolver.ipfsGateways`	`ipfs.io`, then `dweb.link`	Metadata and image fallback order
`resolver.onchfs`	`null`	Onchfs playback is opt-in because it requires worker assets or your proxy
`tzkt`	Public TzKT mainnet/Ghostnet endpoints	Tezos ownership and project reads
`evm.ownershipSource`	`"blockscout"`	Public Blockscout first, then JSON-RPC fallback
`evm.rpcs`	Bundled public RPC lists per EVM chain	Ethereum, Sepolia, Base, and Base Sepolia reads
`concurrency`	`8`	Parallel metadata fetches
React cache	IndexedDB in the browser	Cached data appears before a live refresh

Defaults exposed by the API

Use the exported constants when application code, tests, or a framework-free client need to inspect the same values.

tsx

import {
  DEFAULT_NETWORK_MODE, // "mainnet"
  MAINNET_CHAINS,       // Tezos mainnet, Ethereum, Base
  TESTNET_CHAINS,       // Ghostnet, Sepolia, Base Sepolia
  TEZOS_NETWORKS,       // contracts + default TzKT endpoints
  EVM_NETWORKS,         // factories + default RPC lists
  defaultChainReaderConfig,
} from "@whitehash/chain-reader"

Framework-free client

The React provider fills defaults for you. The lower-level client keeps configuration explicit; use the exported factory when you want the same defaults.

tsx

import {
  createWhitehashClient,
  defaultChainReaderConfig,
} from "@whitehash/chain-reader"

const client = createWhitehashClient(defaultChainReaderConfig())

IPFS gateway order

Gateway roots do not include /ipfs/. Whitehash appends the CID and path, preserving query strings and fragments. Metadata and image requests advance through the array in order.

HTTP, data, and blob URLs pass through unchanged.

One-off override

tsx

const defaults = defaultChainReaderConfig()
const client = createWhitehashClient({
  ...defaults,
  resolver: {
    ...defaults.resolver,
    ipfsGateways: [temporaryGateway],
  },
})

const wallet = useWalletTokens(address, { client })