Introduction to x1id

x1id resolves human-readable names to blockchain addresses on X1. It covers two distinct naming systems:

• @handles — a flat, permanent, ASCII-only namespace (@jack), issued by the on-chain X1 Handle Registry program.
• X1NS domains — the existing hierarchical, subdomain-capable namespace (jack.x1, jack.xnt, jack.xen), which x1id also resolves for compatibility.

Both are read directly from chain state — by the SDK via RPC, or by anyone deriving the accounts themselves. Neither namespace depends on an API being up.

The one invariant that matters

@jack and jack.x1 are different namespaces and can have different owners. Nothing in x1id ever collapses that distinction into a single address.

Every resolved result carries the namespace that matched, and there is no response shape that returns a bare address without it. A query whose text matches both namespace shapes at once — for example @jack.x1 — is refused outright with an ambiguous error. It is never guessed, never resolved to "whichever one exists," and never silently preferred one way. A caller (wallet, dApp, payment form) is expected to show the namespace next to any resolved address before letting a user send funds to it. See Error reference for the full ambiguous contract.

Active constants

Yes, that means the two namespaces are currently on different networks: @handle resolution only works against testnet, while .x1/.xnt/.xen resolution only works against mainnet. This is a real, current constraint — not a documentation error — and it will change once the registry's mainnet deployment ships. The handleProgramId used by the SDK and REST API is configurable, so it can be pointed at a different deployment (e.g. a future mainnet program) without a client update.

What resolution returns today

A successful resolution returns an address for the requested chain, the namespace that matched, and a verification level:

• Address chains: resolution can return an X1 or SOL address today — X1 shares Solana's ed25519 key format, so the same address material works for both. Requesting an ETH or BTC record returns an honest no-record-for-chain error; per-chain records for those chains are on the roadmap and not read yet. x1id never fabricates or falls back to a wrong address for an unsupported chain.
• Verification: @handle resolution reads the registry account's owner directly — a proved control relationship, marked verified. X1NS domain resolution currently reports the domain's owner field, which is a strong signal but not a proved per-chain address record, so it is marked unverified until per-chain profile records are read.
• Subnames / hierarchical handles: @handles are deliberately flat — there is no subname system for handles, by design (the same way @jack doesn't have subdomains on other platforms). This mirrors X1NS's own hierarchical domains only where domains are concerned, not handles.
• Indexer: there is no indexer. Resolution is a direct point lookup — given a name, get an address (or given an address, get its primary name via reverse lookup). Enumerating all handles or all domains owned by an address is out of scope today.

Which integration path is right for you

Next steps