Identify

The call

import { identify } from "@agntn/chains";

const { matches, unchecked } = identify("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
matches.map((chain) => chain.key); // ["solana"]
unchecked; // []

identify("0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984").matches.length; // 13, every EVM chain
identify("0x1").matches.map((chain) => chain.key); // ["aptos", "sui"]

identify(address) partitions the registry: matches holds every chain whose assertAddress accepted the string, unchecked holds every chain that carries no validator and so couldn't be asked. Only InvalidAddressError counts as a miss. Anything else a validator throws is a bug and comes back out.

What a match means

Format only. Every EVM chain shares one format, so a 0x address with 40 hex digits matches all thirteen, and that's the honest answer. A match narrows the family rather than naming the chain an address is used on. Same for 0x1 on Aptos and Sui: both write the framework address that way, and nothing in the string can tell them apart.

A miss on a chain says the string doesn't fit that format. A miss everywhere says no registered format fits, which isn't the same as the address being wrong. It could be a chain this package doesn't know.

Unchecked isn't no

A chain without a validator is named as unchecked rather than skipped, because a silent skip would let "matches none" read as "belongs to no registered chain". The list is empty right now, every built-in chain validates, but a custom chain that skips assertAddress lands there.

On the CLI and in the tools

chains identify 0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984
chains identify EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v --json

identify exits 0 even when nothing matches, because that's an answer too. It prints a warning line in that case and the matching chains otherwise, one per line with the family and the name. --json gives { matches, unchecked } as arrays of keys.

chains_identify_address is the same thing for a model, grouped by family, with the reach of a match spelled out in the text:

"0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984" matches 13 of 29 checked chains.
evm (13): ethereum, base, arbitrum, optimism, polygon, bsc, avalanche, fantom, gnosis, linea, zksync, scroll, berachain
A format match narrows the family; it does not prove the address is used on any of these chains.

The Playground runs the same partition in your browser and lights up the families as you type.