Xmatter: The frontpage for every address on-chain
I’ve been building blockchain applications on and off for years now, and one problem keeps coming back: what is this address? A name, an icon, a symbol. Basic stuff that makes a hex string mean something to a person looking at a screen.
If you’ve built a wallet, a block explorer, or any dapp that shows token info, you’ve had to solve this. The metadata lives everywhere. Token lists maintained by individual projects. GitHub repos like Trust Wallet’s assets. Proprietary databases behind APIs that rate limit you or go away. Chain-specific registries that only cover one network.
None of them agree on a format. None of them cover everything. So every team ends up building their own metadata pipeline, scraping and merging from a dozen sources. I got tired of watching the same problem get solved over and over.
What is Xmatter?
Xmatter is a metadata registry where every smart contract address gets a canonical entry. Each entry is a README.md with YAML frontmatter. Identifiers follow a URL-safe CAIP-10 standard that works across EVM, Solana, and TVM chains.
The registry is just a directory of files:
xmatter/
├─ eip155/1/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2/
│ ├─ README.md
│ └─ icon.png
├─ eip155/56/0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c/
│ └─ README.md
├─ solana/5eykt4usfv8p8njdtrepy1vzqkqzkvdp/...And each README.md:
---
name: WETH
symbol: WETH
decimals: 18
provenance: 'https://github.com/ethereum-optimism/ethereum-optimism.github.io'
standards:
- erc20
icons:
- icon.png
color: '#ec4899'
links:
- name: website
url: 'https://weth.io/'
---Plain files. No database. Readable and forkable by anyone.
Why files
I’ve built enough infrastructure to know that the simplest thing that works is usually the right call. A flat filesystem indexed by path convention gives you a lot for free.
Git becomes your audit trail. Every change is a commit with a timestamp, author, and diff. You get full history and rollback without building any of that. The directory structure maps directly to URL paths, so serve it with any static host and you have a REST API. No application server, no database migrations. Pull requests become governance; anyone can propose a change and review is built into the platform.
Every entry also records where its data came from via a provenance field. When an agent ingests metadata from Trust Wallet’s assets repo, it points back to the source. This is the audit trail that token lists never had.
Automated ingestion
A registry with no data is useless, and adding entries by hand doesn’t scale. So I built an agent system. Small programs that clone well-known upstream repos, read their asset data, and transform it into the Xmatter schema.
There are agents for Trust Wallet’s assets, Ethereum Optimism’s token list, SmolDapp’s token assets, and others. Each agent extends a base class that handles merging: existing keys are never overwritten, only new keys get added. If someone manually curates an entry and drops a LOCK file in the directory, agents won’t touch it.
The agents run on a schedule via GitHub Actions. They pull from upstream, diff against what’s already there, and open PRs. The dataset keeps growing without manual work.
Prefix-indexed lookups
One thing I like about the design is the prefix-indexed existence check. Before fetching metadata for an address, clients check a prefix index to see if the address exists at all. Most lookups for addresses not in the registry short-circuit after a single lightweight request instead of hitting the server with a 404.
The JavaScript client handles this transparently. You call client.has(namespace, chainId, address) and it walks the prefix tree in 2-byte steps. For apps displaying thousands of tokens, this is the difference between a usable integration and one that hammers the API.
Where to find it
Xmatter is open source under MIT. The data, schema, client library, and agents are all in one monorepo. The website at xmatter.org is both the human-readable frontpage and the API endpoint.
If you’re building something on-chain and need metadata for addresses, take a look. If you have metadata to contribute, open a PR.
The repo is at github.com/fuxingloh/xmatter.