ethereum-lists keeps token metadata as one JSON file per contract

One file per token, named by its checksummed address

The layout is the design decision that everything else follows from. Tokens are described in individual, JSON-formatted files, and the filename for each token file should be the ERC-55 formatted Ethereum or other chain address of the token contract, with a .json extension. The project points to a checksum helper web tool at ethsum.netlify.app for getting the mixed-case address right. That single naming rule does a lot of work. Because the file name is the contract address in a canonical mixed-case form, the same token cannot be added twice under two spellings without a reviewer noticing, and a checksum mismatch becomes a natural way to catch a mistyped address. It also means the directory listing is an index of contract addresses, which is a useful artefact in itself. The address format is described as Ethereum or other chain, so the convention extends past the main chain to any contract address that has a checksummed form. The scope of the registry is stated plainly as well: information related to tokens, ERC-20 compliant or compatible only.

The four mandatory fields and what they mean

Four fields are required in every token file, and each one has a constraint that catches a common mistake. The symbol is the short ticker style symbol of the token. The name is the longer human version. The address is the Ethereum or other chain address of the ERC-20 token in ERC-55 mixed-case format, which duplicates the file name by design. The decimals is the decimals of the token, specified as a Number and not a String. That last constraint is the one to watch. Decimals is the single most consequential field in a token registry, because it is the scale factor between the raw integer on chain and the human-readable amount, and a registry that stores it as a string has already lost the type safety that would catch a bad value. Since the fields are mandatory, a file missing any of them is incomplete by the project's own definition, which is the simplest possible validation rule for a contributor-facing format.

Optional fields, including a risk flag array

Beyond the required four, the format has an optional set that is where the interesting entries live. A logo may be included, and the requirement is specific: it must be a square PNG, 128x128 recommended, with a transparent background, compressed using tinypng.com. Support can be a support email, a support URL or another way people can get assistance about the token. GitHub points at where the token or project related code lives, community names the Twitter, Reddit, Slack or other places people gather, and website is the official URL. There is also address_eip1191, the same address in EIP-1191 mixed-case format, which exists because the two checksum specifications disagree about which characters are case sensitive, and a registry that supports both wallets and tooling benefits from carrying both spellings. The field with the most editorial weight is redFlags, an array containing evidence on why the contract should be treated with caution, with the documented example being an object with a type, a comment and a url pointing at the evidence. That is a design decision worth sitting with: the registry does not merely list tokens, it can carry a documented reason to distrust one.

Where the assembled lists actually come from

The repository holds the tokens as single files, and the documentation explains why: it makes it easier for contributors to add new tokens, for reviewers to get a good view of the change, and for merging in tokens from other sources. But the same paragraph is clear that projects will most likely want to use the assembled lists instead. The CI server is already building them. The described path is to go to the commit-list for the master branch and click on the green checkmark behind the last commit, where a build job named kontinuum/run appears, and the details link from there brings you to the assembled files on IPFS. So there are two artefacts here and they serve different purposes. The per-token JSON files are the reviewable source, with one contributor-friendly diff per token. The assembled lists are the distribution form, built by CI and addressed on IPFS by content rather than by tag. If you are building a consumer of this data, you are consuming the CI output, and the practical engineering question becomes how often you refresh it and how you pin it.

Getting the data: clone the repo or take the CI build

There is no install step in the usual sense, because this is a data repository rather than a library, and the documentation does not describe a package to install. The two ways in are the two artefacts described above. If you want to contribute, you clone the repository, add a token as a JSON file under tokens/ named after its checksummed contract address, fill in the four mandatory fields, and open a pull request. Reviewers then see one file per token, which is the stated reason for the layout. If you want to consume the data, you take the assembled lists that CI produces, following the green checkmark on the last commit of the master branch to the kontinuum/run job and from there to the files on IPFS. The build is driven from Gradle, with build.gradle at the root and gradlew alongside it, so the assembly step runs as part of the project's own build rather than as a separate script you invoke. A third path is to read the per-token files directly from the repository, which works fine for a one-off lookup and gives you the newest content rather than the last built version. Whichever route you take, the practical setup work is deciding how your application refreshes its copy, since the documentation gives you the built location but not a polling schedule or a version identifier to pin against.

The Kotlin build and the on-chain check lists

The repository layout reveals more about how the assembled lists are produced. The primary language is Kotlin, and the top level holds a build.gradle, a gradle directory, gradlew and gradlew.bat, a src directory, and a .ci directory alongside .github. The Gradle wrapper files are what tell you the build is meant to be run without a system Gradle install. Two files at the top level are named for a job that sounds like a screening step: onChainCheck.lst and onChainIgnore.lst. The names alone do not tell you their contents or the rule that consumes them, and the documentation does not describe them, so the honest position is that they exist and their exact role is not documented in what is published. The tokens directory holds the per-token files. The overall picture is a data repository with a small amount of build tooling around it, rather than a software project with a large codebase, which is a useful expectation to set before you look at how contributions are reviewed.

Volunteer maintenance is the reliability model

The closing note in the documentation is the one to weigh before depending on this data. The list is maintained by volunteers in the community and people like you around the internet. It may not always be up to date, and it may occasionally get it wrong. If you find an error or omission, the request is to open an issue or make a pull request with corrections. That candour is a strength in the sense that it tells you exactly what you are getting, and a weakness in the sense that there is no SLA, no review SLA and no correction SLA. A token that does not appear at all is a different failure mode from a token that appears with a wrong field, and neither is caught automatically by the format. The maintainers named in the documentation are 409H, associated with EtherAddressLookup, tayvano, associated with MyCrypto, and ligi, associated with WallETH, followed by You, which is a fair signal that this is community infrastructure rather than a vendor service. The listed consumers include WallETH, MyCrypto, MyEtherWallet, TREZOR, pyetherbalance and rainbow-me/rainbow-token-list, and the documentation asks that you say so when you use it.

Where this list is the wrong tool

The boundaries are clear. This registry carries metadata and, optionally, risk evidence. It carries no price, no liquidity depth, no holder distribution and no on-chain state, and the optional fields include a logo but nothing that changes with a transaction. So a team building a swap interface, a price feed or a risk engine that reasons about liquidity cannot treat it as a market data source. The redFlags array is also not a security control. It is a curated, volunteer-maintained annotation with evidence links, which is a different thing from a scanner that inspects a contract, and an entry's absence is not a clean bill of health. If your requirement is contract-level analysis, a registry like this is at best a place to record the result. The other structural limit is the delivery model. Because the assembled lists are built by CI and published on IPFS, a consumer has to decide how to fetch them, how to detect that a new version exists and whether to pin a specific content address for reproducibility, and the documentation does not specify a polling interval or a stable version scheme to key off.

Editorial conclusion

Adopt ethereum-lists if you build a wallet, a block explorer or a token-aware tool and want a volunteer-maintained registry of token metadata that carries optional risk flags alongside the standard fields. Do not adopt it as a source of price or liquidity data, and do not treat the redFlags array as a security guarantee, because the list is maintained by volunteers and the documentation says plainly it may occasionally get things wrong. Verify two things before you wire it in: that the CI build of the assembled lists is the artifact you consume, since the per-token files in the repository are the contributor-facing form rather than the shipped form, and that your checksum handling matches, since the file name is the ERC-55 mixed-case address and a checksum mismatch is how you detect a mistyped contract. The practical first step is to open the tokens directory, pick one contract, and compare its JSON against the fields your own registry expects before you import anything.

Frequently asked questions

Official sources

1. ethereum-lists/tokens on GitHub
2. Issues
3. License: MIT
4. README