Web3 Token Icons

Reusable token-image lookup, caching and refresh hooks for stock PocketBase 0.40.4, with a bounded Go image downloader. Consumers supply independent credentials; the service owns provider lookup, persistent queueing and files.

Interface

GET /api/scgui-token-icons/resolve/{chain}/{address} resolves one EVM token. POST /api/scgui-token-icons/resolve/batch accepts {chainId, addresses} with at most 30 addresses. It deduplicates addresses, batches DEX Screener lookups, and batches GeckoTerminal fallback lookups. Responses include image URL, symbol, cache status and retry interval. Both routes and GET /api/scgui-token-icons/health require X-SCGUI-Icon-Key.

The service stores chains, cached images and private queue/control state in icon_chains, token_icons and icon_control. The separate otterscan-token-icons adapter delegates asset, health and scheduled refresh requests to this service.

Build and validation

Use Node.js 22 and Go 1.26. Run npm ci and npm run build. The dist/ directory contains hooks, migrations and a checksum manifest for the hook files. Build the downloader from the repository root:

ICON_VERSION="$(node -p "require('./package.json').version")"
go build -ldflags "-X main.version=$ICON_VERSION" -o web3-token-icons ./cmd/web3-token-icons

The binary supports version and download -url <provider-image-url>; download returns validated image bytes on stdout.

Run npm run test:policy, go test ./... and go vet ./.... Native tests require PocketBase 0.40.4: set POCKETBASE_BINARY for npm test and POCKETBASE_BIN for npm run test:refresh.

Configuration and deployment

The mode-0600 pb_hooks/.environment/scgui-icons.json contains publicBase and consumerHashes, an array of SHA-256 hashes of independent consumer keys. Shared source and worker hashes live in .environment/token-icons.json; see config.example.json. Optional downloaderPath selects the installed helper. The compatible default is .environment/icu-sc-gui-token-icons. Keep settings, credentials and connection files outside the repository.

node deploy.mjs --connection <file> --settings <file> --credentials <file> --artifact dist verifies artifacts, activates the hook and checks shared and adapter health. --dry-run validates without uploading. Connection fields are iconInstance, host, optional port and identityFile, and user; credentials contain the staging consumer key used for health verification. This deployment command targets the existing web3-token-icons instance.

The deployment command updates hooks; it does not upload or apply dist/pb_migrations. Apply reviewed migrations separately through the target instance's native PocketBase migration workflow. The unused-auth migration locks all seven ordinary users API/auth rules without deleting accounts or changing _superusers; it is intended only for instances that do not use ordinary accounts.

Hook-only updates preserve installed adapters and downloader files. For a full artifact, pass both --adapter <adapter-hook> and --downloader <binary> to node build.mjs. Preserve existing collections, private settings and scheduled webhooks during upgrades; database failures must never trigger reinitialization.

Image sources

Token images: DEX Screener · Powered by GeckoTerminal. DEX Screener is queried first; GeckoTerminal supplies fallback images. Consumers should credit the source of displayed data according to the GeckoTerminal attribution guide when using that provider.

License

MIT — see LICENSE.