From 3038a168a5aa6d80239dfd2e2c4207ba9125cb65 Mon Sep 17 00:00:00 2001 From: Harpreet Singh Date: Fri, 13 Nov 2026 03:33:25 +0530 Subject: [PATCH 1/7] docs: cut Universal Usernames to a why page and an endpoint how-to Cover onchain naming services alongside apps with their own database, since both build the same HTTP endpoint. Detailed product education moves to the landing page. Co-Authored-By: Claude Opus 5.5 --- developer-guide/guide/universal-usernames.mdx | 512 +++++------------- overview/universal-usernames.mdx | 74 +-- 2 files changed, 151 insertions(+), 435 deletions(-) diff --git a/developer-guide/guide/universal-usernames.mdx b/developer-guide/guide/universal-usernames.mdx index 09adaf3..34d11b8 100644 --- a/developer-guide/guide/universal-usernames.mdx +++ b/developer-guide/guide/universal-usernames.mdx @@ -1,166 +1,99 @@ --- -title: "Connect your usernames to ENS" -description: "Serve ENS names for your users from your own username API." +title: "Build a Universal Usernames endpoint" +description: "Serve ENS names for your users from the username system you already run." sidebarTitle: "Universal usernames" icon: "at" --- -import { FlowExplainer } from '/snippets/flow-explainer.jsx' +This guide walks you through building the one endpoint Universal Usernames needs, then connecting it to your ENS name. When you're done, `happy` in your app resolves as `happy.brand.eth` in any ENS-aware wallet. -Your users already have usernames in your app. Universal Usernames gives each of them a matching ENS name: `happy` in your app becomes `happy.brand.eth`, and any ENS-aware wallet can send to it, show its avatar, or read its profile. - -You don't move or copy any users. You add one small endpoint, the adapter, on top of the username service you already run. Namespace calls it whenever someone looks up a name under `brand.eth`. For the product side, read the [Universal usernames overview](/overview/universal-usernames). - -## How a lookup works - - - -Here is what happens when a wallet resolves `happy.brand.eth`: - -1. **The wallet asks ENS.** The ENS registry points it to the resolver set on `brand.eth`, which is the Namespace Hybrid Resolver with Universal Usernames turned on. -2. **The resolver hands off.** It can't answer from chain data, so it tells the wallet to ask the Namespace gateway instead, using [CCIP-Read (EIP-3668)](https://eips.ethereum.org/EIPS/eip-3668). Wallets that support ENS follow this automatically. -3. **The gateway finds your adapter.** It looks up the endpoint URL and optional bearer token saved for `brand.eth`. -4. **The gateway calls your adapter.** It sends `GET {your endpoint}/happy`. -5. **Your adapter answers.** It reads `happy` from your database and returns the profile as JSON: addresses, text records and an optional contenthash. -6. **The gateway signs.** It picks the record the wallet asked for, such as the Base address or the avatar, converts it to ENS format and signs it. -7. **The resolver verifies.** The wallet passes the signed answer back to the resolver, which checks the signature and returns the record. - -Your database stays the source of truth. Namespace stores your endpoint URL and token, never your users or their records. - -## What you'll set up - -The work has two parts: - -1. **Build the adapter.** Add a route to your existing username service that returns a user's profile in the format below. -2. **Connect it in the Namespace App.** Save the endpoint, check it with a few real usernames, then set the resolver on `brand.eth` so lookups reach the adapter. - -After that, every username your adapter knows resolves as an ENS name, and there's nothing to mint or sync. +The endpoint is a small HTTP service. It takes a username, reads that user from wherever your usernames live, and returns a profile in the format below. Where they live doesn't matter: a database behind your app, or a registry contract if you run a naming service. For why this works and what to decide first, read the [Universal usernames overview](/overview/universal-usernames). ## Prerequisites -- A second-level `.eth` name, such as `brand.eth`, owned by a wallet you control. That wallet signs in to the Namespace App and sends the resolver transaction. -- A username service you can add a public HTTPS route to. -- Usernames that are valid ENS labels. The gateway only asks for single, [ENSIP-15](https://docs.ens.domains/ensip/15) normalized labels, which means lowercase and no dots. If your usernames allow uppercase, match against a lowercased copy. - -## Step 1: Build the adapter - -The adapter is one `GET` route. It takes a username and returns that user's public profile. Everything below is what the gateway expects from it. - - -In the Namespace App, the **Build with AI** tab on the Universal Usernames page has a prompt you can paste into a coding agent. It describes the same contract as this section. - - -### Pick the endpoint URL +- An ENS name such as `brand.eth`, owned by a wallet you control. +- Somewhere to host a public HTTPS route. +- Usernames that are valid [ENSIP-15](https://docs.ens.domains/ensip/15) labels: lowercase, no dots. If yours allow uppercase, match against a lowercased copy. -You save one base URL per parent name, for example `https://api.brand.example/ens`. The gateway adds the username as the last path segment. The URL must follow these rules: +## Step 1: Build the endpoint -- `https://` only. -- No username or password, no query string (not even a bare `?`), and no fragment. -- At most 2048 characters. -- A path is fine. Trailing slashes are removed, so `https://api.brand.example/ens/` and `https://api.brand.example/ens` behave the same. +### The request -### Handle the request - -For `happy.brand.eth`, the gateway sends: +You pick a base URL, such as `https://api.brand.example/ens`. For `happy.brand.eth`, the Namespace gateway sends: ```http GET /ens/happy HTTP/1.1 Host: api.brand.example Accept: application/json Accept-Encoding: identity -User-Agent: Namespace-UniversalUsernames/1 Authorization: Bearer YOUR_TOKEN ``` -- The last path segment is the username, URL-encoded. `zoë` arrives as `/ens/zo%C3%AB`, so decode it before you look the user up. -- The username is already normalized. Compare it against a normalized copy of your usernames, not the casing users typed. -- `Authorization` is only sent when you saved a bearer token. -- Only single labels reach you. Nested names such as `a.happy.brand.eth`, and labels that aren't normalized, get empty records without a call to your adapter. - -### Return the right status - -| Your status | What happens | -| --- | --- | -| `200` with a profile | The gateway reads the requested record from the profile. | -| `404` | The user doesn't exist. The wallet gets an empty record. | -| `401` or `403` | The lookup fails. Check the saved bearer token. | -| `429` | The lookup fails. Don't rate-limit the gateway below your real traffic. | -| `3xx` | The lookup fails. Redirects are never followed. | -| Any other status | The lookup fails. | - -A `200` response must also: +- The last path segment is the username, URL-encoded and already normalized. Decode it before you look it up. +- `Authorization` is only sent if you save a bearer token in the App. +- Only single labels reach you. Nested names like `a.happy.brand.eth` never call your endpoint. -- Use `Content-Type: application/json`. Parameters such as `; charset=utf-8` are fine. -- Be uncompressed. The gateway asks for `identity`, and any other `Content-Encoding` fails the lookup. Check that your CDN or proxy respects this. -- Be at most 262,144 bytes (256 KiB), UTF-8. -- Arrive in full within 5 seconds, DNS lookup included. +### The response -### Serve it from a public host +Return `200` with this JSON for a user that exists, and `404` for one that doesn't: -- Your hostname must resolve only to public IPv4 or IPv6 addresses. If any answer is private, loopback, link-local or reserved, the gateway refuses to connect. -- TLS is verified against your hostname, so use a valid certificate. -- The gateway calls you server to server, so CORS doesn't affect resolution. You only need CORS for the [endpoint check](#step-2-connect-it-in-the-namespace-app) in the Namespace App. - -### Return the profile - -Every `200` response is one profile in schema version 1. +```json happy.json +{ + "version": 1, + "username": "happy", + "texts": { + "name": "Happy", + "avatar": "https://cdn.brand.example/avatars/happy.png", + "com.twitter": "happy" + }, + "addresses": { + "2147483648": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", + "0": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq", + "501": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM" + } +} +``` - Must be the number `1`. The string `"1"` fails. + Always the number `1`. - Must equal the requested username exactly, after decoding. If you return `Happy` for a request for `happy`, every lookup for that user fails. + The requested username, exactly as it arrived after decoding. - ENS text records, keyed by text record key. Use `{}` when there are none. At most 128 keys. See [Add text records](#add-text-records). + [ENSIP-5](https://docs.ens.domains/ensip/5) text records such as `name`, `avatar`, `description`, `url` and `com.twitter`. Use `{}` for none. - Address records, keyed by ENS coin type as a decimal string. Use `{}` when there are none. At most 128 keys. See [Add addresses](#add-addresses). + Addresses keyed by ENS coin type as a decimal string. Use `{}` for none. See [Address keys](#address-keys). - Optional. A content URI such as `ipfs://...`. Leave the field out when there is none, because `null` or `""` fails contenthash lookups. See [Add a contenthash](#add-a-contenthash). + Optional. An `ipfs://`, `ipns://`, `ar://` or other [ENSIP-7](https://docs.ens.domains/ensip/7) URI. Leave it out when there is none. -Any other top-level field fails the whole profile. +Any other top-level field fails the profile. -```json Example profile for happy.brand.eth -{ - "version": 1, - "username": "happy", - "texts": { - "name": "Happy", - "description": "Building on Brand", - "avatar": "https://cdn.brand.example/avatars/happy.png", - "url": "https://brand.example/happy", - "com.twitter": "happy" - }, - "addresses": { - "2147483648": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", - "2147492101": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", - "0": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq", - "501": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM" - }, - "contenthash": "ipfs://QmYwAPJzv5CZsnAzt8auVZRnGiRAzQmmJYDh4T7SEBuwNA" -} -``` +### Address keys -The gateway checks the outer shape (`version`, `username`, the two objects and their sizes) on every lookup. Record values are only checked when a wallet asks for that record. A malformed avatar fails `avatar` lookups but leaves the user's addresses working. +- `2147483648` is the default EVM address. It answers for Ethereum and every EVM chain without its own key, so most users need only this one. +- Add `0x80000000 | chainId` for a chain where the address differs. Base (`8453`) is `2147492101`. viem's `toCoinType(chainId)` does the math. +- Non-EVM chains use their [SLIP-44](https://github.com/satoshilabs/slips/blob/master/slip-0044.md) number: Bitcoin is `0`, Solana is `501`. +- Return EVM addresses checksummed. Bitcoin addresses must be mainnet. -### Example adapter +### Example endpoint -This route handler uses the web-standard `Request` and `Response`, so it works as a Next.js App Router route (`app/ens/[label]/route.ts`) on the Node.js runtime, or in any server that speaks Fetch. Swap `findUserByUsername` for your own lookup. `buildAddresses` comes from [Build the addresses map](#build-the-addresses-map). +This route uses web-standard `Request` and `Response`, so it runs as a Next.js App Router route (`app/ens/[label]/route.ts`) or in any server that speaks Fetch. Swap `findUserByUsername` for your own lookup. ```ts route.ts import { timingSafeEqual } from 'node:crypto'; -import { buildAddresses } from './addresses'; +import { getAddress } from 'viem'; import { findUserByUsername } from './users'; -// Optional. Set the same value as the bearer token in the Namespace App. const BEARER_TOKEN = process.env.UUN_BEARER_TOKEN; +const DEFAULT_EVM_COIN_TYPE = '2147483648'; function isAuthorized(request: Request): boolean { if (!BEARER_TOKEN) return true; @@ -171,329 +104,136 @@ function isAuthorized(request: Request): boolean { ); } -// GET {endpointUrl}/{label} +// GET {base URL}/{username} export async function GET(request: Request): Promise { if (!isAuthorized(request)) return new Response(null, { status: 401 }); const segment = new URL(request.url).pathname.split('/').pop() ?? ''; - let label: string; + let username: string; try { - label = decodeURIComponent(segment); + username = decodeURIComponent(segment); } catch { return new Response(null, { status: 404 }); } - const user = await findUserByUsername(label); + const user = await findUserByUsername(username); if (!user) return new Response(null, { status: 404 }); - // Only fields the user has chosen to make public: anyone can read them. + // Anyone can read these, so publish only what the user chose to share. const texts: Record = {}; if (user.displayName) texts.name = user.displayName; - if (user.bio) texts.description = user.bio; if (user.avatarUrl) texts.avatar = user.avatarUrl; - if (user.twitter) texts['com.twitter'] = user.twitter; - - return Response.json({ - version: 1, - username: label, - texts, - addresses: buildAddresses(user.wallets), - }); -} -``` -`findUserByUsername(label)` returns `null` when there's no match, and otherwise a user with `wallets: Wallet[]` plus optional `displayName`, `bio`, `avatarUrl` and `twitter`. `Response.json` sets `Content-Type: application/json` for you. - -### Test the adapter - -Call it the way the gateway will: + const addresses: Record = {}; + if (user.walletAddress) { + addresses[DEFAULT_EVM_COIN_TYPE] = getAddress(user.walletAddress); + } -```bash -curl -i https://api.brand.example/ens/happy \ - -H 'Accept-Encoding: identity' \ - -H 'Authorization: Bearer YOUR_TOKEN' + return Response.json({ version: 1, username, texts, addresses }); +} ``` -Expect `200`, `content-type: application/json`, no `content-encoding` header, and a body whose `username` is `happy`. An unknown username should return `404`: - -```bash -curl -s -o /dev/null -w '%{http_code}\n' https://api.brand.example/ens/no-such-user -``` +```ts users.ts +export type User = { + displayName?: string; + avatarUrl?: string; + walletAddress?: string; +}; -```bash -404 +// Replace with a query against your users table. +export async function findUserByUsername(username: string): Promise { + throw new Error(`findUserByUsername is not implemented: ${username}`); +} ``` -## Step 2: Connect it in the Namespace App +### If your usernames live onchain -Once the adapter answers correctly, point `brand.eth` at it. +Running a naming service with its own registry? Keep the same route and read the user from your contract instead. This version of `findUserByUsername` reads the address with viem. Replace the ABI and function with your registry's own lookup. - - - Go to [Universal Usernames](https://app.namespace.ninja/universal-usernames), connect the wallet that owns `brand.eth`, and select the name. - - - Enter the base URL, for example `https://api.brand.example/ens`. If your adapter requires a bearer token, enter it too. Namespace sends it as `Authorization: Bearer ` and never shows it again after you save. - - - Type a username that exists in your app into **Sample username** and select **Check endpoint**. The App fetches `{endpoint}/{username}` and shows how many text records and addresses came back. Try a few users, including one with no wallets and one that doesn't exist, which should report a `404`. +```ts users.ts +import { createPublicClient, http, parseAbi, zeroAddress } from 'viem'; - The check runs in your browser, so your adapter has to allow `https://app.namespace.ninja` with CORS (`Access-Control-Allow-Origin`, plus `Access-Control-Allow-Headers: Authorization` if you use a token). The check is optional, and you can save even if it fails. - - - Save the endpoint. The gateway picks up a new or changed endpoint within about 5 seconds. - - - The App shows the transaction `brand.eth` needs: +const client = createPublicClient({ transport: http(process.env.RPC_URL) }); - - **Set resolver** or **Update resolver** if `brand.eth` isn't on the Namespace Hybrid Resolver yet. If the name already has records, such as its own address or avatar, you can first **Transfer records** so they keep resolving on the new resolver. - - **Enable Universal Usernames** if `brand.eth` is already on the Hybrid Resolver for something else. - - Send the transaction. When the step shows **Resolver set and configured**, every `username.brand.eth` resolves from your adapter. - - - - -`brand.eth` serves one kind of subname at a time. If it serves offchain subnames or L2 subnames today, those stop resolving once you switch, and your adapter answers for every subname instead. The App warns you before the switch. - - -### Resolve a name - -Resolve one of your users like any ENS name. With viem: - -```ts resolve.ts -import { createPublicClient, http, toCoinType } from 'viem'; -import { base, mainnet } from 'viem/chains'; -import { normalize } from 'viem/ens'; - -const rpcUrl = process.env.ETH_RPC_URL; -if (!rpcUrl) throw new Error('Missing ETH_RPC_URL'); - -const client = createPublicClient({ chain: mainnet, transport: http(rpcUrl) }); -const name = normalize('happy.brand.eth'); - -const [ethAddress, baseAddress, displayName, avatar] = await Promise.all([ - client.getEnsAddress({ name }), - client.getEnsAddress({ name, coinType: toCoinType(base.id) }), - client.getEnsText({ name, key: 'name' }), - client.getEnsText({ name, key: 'avatar' }), +const REGISTRY_ADDRESS = process.env.REGISTRY_ADDRESS as `0x${string}`; +const REGISTRY_ABI = parseAbi([ + 'function resolve(string name) view returns (address)', ]); -console.log({ ethAddress, baseAddress, displayName, avatar }); -``` - -For a Sepolia name, use `chain: sepolia` and a Sepolia RPC URL. A user your adapter returns `404` for resolves to `null`. - -### How changes show up - -| What | How long | Effect | -| --- | --- | --- | -| Profile responses, including `404` | 60 seconds from the fetch | A profile change can take up to 60 seconds to reach wallets. | -| Endpoint URL and bearer token | About 5 seconds | A new URL or token is used shortly after you save. | -| Failed fetches | Not cached | The next lookup calls your adapter again. | - -Concurrent lookups for the same user share one request, and one profile answers every record a wallet asks for. Wallets and RPC providers may cache on their side too. - -You can change the endpoint or token at any time on the same page, or remove it. If you remove the endpoint while `brand.eth` still points to Universal Usernames, its subnames stop resolving until you save a new one. - -## Add addresses - -Addresses are what make a name useful for payments, so this is the part most worth getting right. - -### Key them by coin type - -Each key in `addresses` is an ENS coin type written as a decimal string, with no leading zeros and no hex. Each value is the address in its usual text format. - -- Ethereum mainnet is `60`. -- Every other EVM chain uses `0x80000000 | chainId` ([ENSIP-11](https://docs.ens.domains/ensip/11)). Base (chain `8453`) is `2147483648 + 8453 = 2147492101`. viem's `toCoinType(chainId)` does this math. -- `2147483648` (`toCoinType(0)`) is the default EVM address. It answers for Ethereum and for any EVM chain that has no key of its own. -- Non-EVM chains use their [SLIP-44](https://github.com/satoshilabs/slips/blob/master/slip-0044.md) number ([ENSIP-9](https://docs.ens.domains/ensip/9)). - -| Chain | Coin type | Address format | -| --- | --- | --- | -| Default EVM address | `2147483648` | `0x` + 40 hex characters | -| Ethereum | `60` | `0x` + 40 hex characters | -| OP Mainnet (10) | `2147483658` | `0x` + 40 hex characters | -| Base (8453) | `2147492101` | `0x` + 40 hex characters | -| Arbitrum One (42161) | `2147525809` | `0x` + 40 hex characters | -| Bitcoin | `0` | Mainnet base58 (`1...`, `3...`) or bech32/bech32m (`bc1...`) | -| Litecoin | `2` | Base58 (`L...`, `M...`) or bech32 (`ltc1...`) | -| Dogecoin | `3` | Base58 (`D...`) | -| Solana | `501` | Base58 public key | - -Any EVM chain ID works. For other non-EVM chains, look up the coin type in the [address-encoder coin list](https://github.com/ensdomains/address-encoder). An unknown coin type fails lookups for that key. - -### Use the default EVM address - -If a user has the same address on every EVM chain, set only `2147483648`. When a wallet asks for Ethereum, Base or any other EVM chain and your profile has no key for it, the gateway answers with the default address ([ENSIP-19](https://docs.ens.domains/ensip/19)). Add chain-specific keys only where an address differs. - -Non-EVM coin types have no fallback. A key that exists but holds an invalid address fails that lookup and never falls back to the default. - -### Get the format right - -The gateway converts each address to ENS binary format with [`@ensdomains/address-encoder`](https://github.com/ensdomains/address-encoder): - -- EVM addresses are `0x` plus 40 hex characters, EIP-55 checksummed or all lowercase. Mixed case with a wrong checksum fails, so return checksummed addresses (viem's `getAddress` does this). -- Bitcoin addresses must be mainnet. Testnet addresses such as `tb1...` fail. -- Solana addresses are the base58 public key. -- Each value can be up to 1024 characters. - -### Build the addresses map - -This module turns a user's wallets into the `addresses` object. It validates each address with the same library the gateway uses, so a bad address shows up in your logs instead of breaking a lookup. - -```bash -npm install viem@2 @ensdomains/address-encoder@2 -``` - -```ts addresses.ts -import { getCoderByCoinType } from '@ensdomains/address-encoder'; -import { getAddress, toCoinType } from 'viem'; - -// ENSIP-9 coin types (SLIP-44) for non-EVM chains. -const SLIP44_COIN_TYPES = { - bitcoin: 0, - solana: 501, -} as const; - -export type Wallet = - // chainId 0 is the default EVM address, used for every EVM chain without its own record. - | { chain: 'evm'; chainId: number; address: string } - | { chain: keyof typeof SLIP44_COIN_TYPES; address: string }; - -export function coinTypeOf(wallet: Wallet): number { - if (wallet.chain === 'evm') return Number(toCoinType(wallet.chainId)); - return SLIP44_COIN_TYPES[wallet.chain]; -} - -/** Builds the profile `addresses` map, keyed by decimal coin type. */ -export function buildAddresses(wallets: Wallet[]): Record { - const addresses: Record = {}; - for (const wallet of wallets) { - const coinType = coinTypeOf(wallet); - const address = - wallet.chain === 'evm' ? getAddress(wallet.address) : wallet.address; - // Same library and check the gateway runs, so a bad address fails here - // instead of failing the lookup. - getCoderByCoinType(coinType).decode(address); - addresses[String(coinType)] = address; - } - return addresses; +export type User = { + displayName?: string; + avatarUrl?: string; + walletAddress?: string; +}; + +export async function findUserByUsername(username: string): Promise { + const walletAddress = await client.readContract({ + address: REGISTRY_ADDRESS, + abi: REGISTRY_ABI, + functionName: 'resolve', + args: [username], + }); + if (walletAddress === zeroAddress) return null; + return { walletAddress }; } ``` -For these wallets: +Every lookup hits your RPC, so use a reliable provider. The gateway caches each profile for 60 seconds. -```ts -buildAddresses([ - { chain: 'evm', chainId: 0, address: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045' }, - { chain: 'evm', chainId: 8453, address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' }, - { chain: 'bitcoin', address: 'bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq' }, - { chain: 'solana', address: '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM' }, -]); -``` - -the result is: +### Test it -```json -{ - "0": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq", - "501": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", - "2147483648": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", - "2147492101": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" -} +```bash +curl -i https://api.brand.example/ens/happy -H 'Authorization: Bearer YOUR_TOKEN' ``` -`buildAddresses` throws on an invalid address. Catch the error where you build the profile if you'd rather drop one bad wallet than fail the whole response. - -## Add text records - -`texts` holds [ENSIP-5](https://docs.ens.domains/ensip/5) text records. Wallets and apps read the keys they support, so stick to the common ones: - -| Key | Value | -| --- | --- | -| `name` | Display name | -| `avatar` | `https://` image URL, `ipfs://` URI, or an NFT reference ([ENSIP-12](https://docs.ens.domains/ensip/12)) | -| `header` | Banner image, same formats as `avatar` | -| `description` | Short bio | -| `url` | Website | -| `email` | Public email address | -| `location` | Free-form location | -| `com.twitter` | X handle, without `@` | -| `com.github` | GitHub username | -| `com.discord` | Discord username | -| `org.telegram` | Telegram username | +Expect `200`, `content-type: application/json` and `"username": "happy"`. An unknown username should return `404`. -Keys are case-sensitive. Don't put a display name in `display`, because ENSIP-5 reserves that key for the name itself in a preferred casing. +### Rules the gateway enforces -Limits: up to 128 keys, each key 1 to 256 characters, each value up to 4096 characters. Values must be strings, so a number or `null` fails lookups for that key. Leave a key out when the user has no value. +The gateway fails the lookup instead of guessing, so check these before you go live: -## Add a contenthash +- The base URL is `https://`, with no query string or fragment, up to 2048 characters. +- The host resolves to public IPs only and has a valid TLS certificate. +- The response is `application/json`, uncompressed, at most 256 KiB, and arrives within 5 seconds. +- Redirects, `401`, `403`, `429` and `5xx` all fail the lookup. Only `404` means "no such user". +- At most 128 text records and 128 addresses. -`contenthash` links the name to a website or file, so `happy.brand.eth` can open in browsers that support ENS sites. It must be a URI with one of these schemes ([ENSIP-7](https://docs.ens.domains/ensip/7)): - -| Scheme | Format after `://` | -| --- | --- | -| `ipfs://` | IPFS CID | -| `ipns://` | IPNS name (a CID, such as `k51...`) | -| `ar://` | Arweave transaction ID, 43 characters | -| `onion3://` | Tor v3 address, 56 characters | -| `sia://` | Skynet ID, 46 characters | -| `bzz://` | Swarm hash, 64 hex characters | - -A bare CID without a scheme, an `https://` URL, or any other scheme fails contenthash lookups. Maximum length is 4096 characters. - -## Pros and cons - -Universal Usernames fits when you already run a username system and want it to work outside your app. It isn't the right choice for every product. - -What you get: - -- Every existing username resolves as soon as the resolver is set. Nothing is minted, copied or kept in sync. -- One transaction on `brand.eth` covers every username, current and future. -- Users change their avatar or add a wallet in your app, and wallets see it within 60 seconds. -- Ethereum, any EVM chain, Bitcoin, Solana and other chains sit side by side under the same name. -- Wallets, explorers and apps that resolve ENS names with CCIP-Read need no integration with you. +## Step 2: Connect it in the Namespace App -What to weigh: + + + Open [Universal Usernames](https://app.namespace.ninja/universal-usernames), connect the wallet that owns `brand.eth`, and enter your base URL and optional bearer token. + + + Enter a real username and select **Check endpoint**. The check runs in your browser, so allow `https://app.namespace.ninja` with CORS (plus `Access-Control-Allow-Headers: Authorization` if you use a token). It's optional. + + + Send the transaction the App shows. When it reads **Resolver set and configured**, every `username.brand.eth` resolves from your endpoint. + + -- Your uptime is the name's uptime. If your adapter is down, slow or returns bad JSON, lookups for your users fail. There's no fallback copy. -- Wallets trust the gateway's signature, not a proof from your database. This is the same trust model as other offchain ENS names. -- Users don't own the names onchain. The name follows your database, so users can't transfer it or hold it as an NFT, and you can rename or remove it at any time. -- Universal Usernames replaces offchain or L2 subnames under the same parent name. -- The gateway answers address, text and contenthash records. Other ENS record types aren't served. -- Most major wallets follow CCIP-Read, but not every app does. Test the ones your users rely on. + +A name serves one kind of subname at a time. If `brand.eth` already serves offchain or L2 subnames, those stop resolving once you switch. + -If you'd rather Namespace store the names and records for you, use [offchain subnames](/developer-guide/guide/create-offchain-subnames). If users should own their names onchain, use [L1 or L2 subnames](/developer-guide/guide/mint-l1-l2-subnames). +Profile changes reach wallets within 60 seconds. A new endpoint or token takes effect within about 5 seconds. -## Security practices +## Before you go live -Your adapter now decides where money goes when someone sends to `happy.brand.eth`. Treat it like a payments endpoint. +Your endpoint now decides where payments to your users go. -- **Publish only what users chose to share.** Anyone can resolve any username and read every record in its profile. Leave out private fields, internal IDs and unverified data. -- **Hide accounts that shouldn't be found.** Anyone can guess usernames and see which ones resolve. Return `404` for private, suspended or deleted accounts. -- **Serve only addresses the user controls.** A wrong address means lost funds. Store addresses the user has proven they own, for example with a signature, and never fill in an address on their behalf. -- **Don't recycle usernames quickly.** If `happy` is deleted and someone else claims it, payments sent to `happy.brand.eth` go to the new user. Keep released usernames reserved for a while, and remember the 60-second cache. -- **Require a bearer token.** It lets your adapter reject callers other than Namespace. Compare it in constant time, as in the [example adapter](#example-adapter). Namespace stores it encrypted, bound to your parent name, and sends it only in the `Authorization` header to your endpoint. It can be up to 4096 characters. -- **Rotate the token without downtime.** Make your adapter accept both the old and new tokens, save the new one in the App, wait about 5 seconds, then drop the old one. -- **Re-enter the token when you move hosts.** If you change the endpoint's scheme, host or port, the App drops the saved token unless you enter it again. That stops a token from following a changed endpoint to a server it wasn't meant for. -- **Protect the wallet that owns `brand.eth`.** Only that wallet can save, change or remove the endpoint and set the resolver, and API keys can't. Whoever holds it can redirect every username. Use a hardware wallet or a multisig, and know that the endpoint control moves with the name if it changes hands. -- **Rate-limit with care.** A `429` fails the lookup. Set limits that fit your real lookup volume rather than blocking the gateway. -- **Keep usernames out of your logs if you can.** Namespace's gateway logs record the parent name, a hash of the username, the record type, the outcome and latency. They never contain usernames, record values, profile bodies or the token. +- Return `404` for private, suspended or deleted accounts. Anyone can guess usernames. +- Serve only addresses the user has proven they control. +- Don't hand a released username to someone new right away, or payments meant for the old user go to them. +- Require a bearer token, and keep the wallet that owns `brand.eth` on a hardware wallet or multisig. ## Next steps - Why Universal Usernames exist and what to decide before you build. + Why it works and what to decide before you build. - Save your endpoint and set the resolver in the Namespace App. - - - Let Namespace store the names and records instead of your own endpoint. - - - Bring your existing naming service and we'll map it onto ENS with you. + Save your endpoint and set the resolver. diff --git a/overview/universal-usernames.mdx b/overview/universal-usernames.mdx index d42b4ba..73ae970 100644 --- a/overview/universal-usernames.mdx +++ b/overview/universal-usernames.mdx @@ -1,84 +1,60 @@ --- title: "Universal usernames" -description: "Connect ENS to your existing usernames." +description: "Make the usernames you already issued work outside your app." sidebarTitle: "Universal usernames" icon: "globe" --- import { FlowExplainer } from '/snippets/flow-explainer.jsx' -## Two ways teams create usernames today +## Why it's needed -Almost every product that ships usernames picks one of two approaches. Both leave the user stuck at the same place. +Your users already have a username, like `@happy`. Inside your app it works: people send money to it, find each other with it, and see it on leaderboards. -**Plain usernames:** usually displayed like `@alice` or `alice`. Fast to build, and inside your app they work exactly as intended. But the name only exists in your database. Send `@alice` to someone in another wallet or app, and it simply won't work. Users are back to copying and pasting an address. +Outside your app, it doesn't exist. A friend in another wallet can't pay `@happy`, so they ask for an address and paste `0x71C7…F2a9`. That's slow, and one wrong character sends the money somewhere it can't come back from. -**A custom TLD:** something like `alice.wallet` or `alice.pay`, whatever reads well next to your brand name. This looks like the better option but it's not. Your TLD isn't in DNS and isn't in ENS, so no wallet outside your product has any way to look it up. Making it work means asking every wallet, explorer, and app to integrate your naming system one at a time. Also, collisions are the other half of the problem: multiple projects have built competing versions of the same TLD, so `alice.wallet` can resolve to two different people depending on which app you ask. +Naming services with their own TLD run into the same wall. `happy.brand` only resolves in the apps that integrated it, and every other wallet has to be convinced one at a time. -## A better way with ENS +## What Universal Usernames does -Every username you've already issued gets a matching ENS name. One rule, applied across your whole user base: +Every username you've issued gets a matching ENS name, under one rule: ``` -Your username: happy.brand +Your username: happy ENS name: happy.brand.eth - or happy.brand.id, using a domain you already own + or happy.brand.id, using a DNS domain imported into ENS ``` -Your system stays the source of truth and no data moves. The username just gains a form that ENS-aware wallets already know how to read. +Wallets, explorers and apps that already read ENS can resolve it, with no integration on their side. You don't move users, mint names or sync records. Your system stays the source of truth. - -This does not turn `.brand` into a new ENS top-level domain. Each user gets an ENS name for the identity they already have. - +## How it works -## ENS isn't limited to .eth or Ethereum - -Two (wrong) assumptions people usually make. - -**You don't need a `.eth` name.** - -`happy.brand.eth` and `happy.brand.id` resolve identically. The first means registering `brand.eth`. The second means taking a domain you already own, turning on DNSSEC, and [importing it into ENS](https://docs.ens.domains/learn/dns/). Same result, so pick on branding. - -**ENS isn't only for Ethereum.** - -One name holds a separate address record for every chain, and they don't have to be EVM chains. Bitcoin, Solana, Base, Arbitrum, and Ethereum sit side by side on the same name, along with profile fields like display name and avatar. Your user has one name and it works everywhere they hold funds. - -## Follow one lookup - -The diagram is a single name being looked up, start to finish. Its two toggles are the decisions above: the parent name, and where records are read from. Neither changes the path. - -It loops on its own. Hover to pause, or use the dots to step through it. +You build one HTTP endpoint that takes a username and returns that user's public profile: addresses, avatar and other records. Then you point your ENS name at Namespace. When a wallet looks up `happy.brand.eth`, Namespace calls your endpoint, signs the answer and hands it back. -Nothing there asked you to move your users, usernames, or records. The wallet asked a question, your system answered, the wallet showed the result. - -## Your records stay where they are - -Records can live in the database you run today, on an L2, or on another chain. No second registry on Ethereum, nothing to keep in sync. Whatever answers the question inside your product answers it here too. +The endpoint reads from wherever your usernames live. A neobank, wallet or payments app reads its own database. A naming service with names onchain reads its registry contract or indexer. Both return the same JSON, so the rest of the setup is identical. ## Decide before you build -1. **The naming rule.** A parent name and a predictable pattern, such as `happy.brand` becoming `happy.brand.eth`. Nobody should have to learn a second identity. -2. **Where the answer comes from.** Your database, a contract in your existing registry, or a proof Ethereum can verify. -3. **Who runs it.** Someone holds the parent name, keeps the lookup path online, and fixes it when it breaks. +- **The parent name.** `brand.eth`, or a domain you already own. Usernames need to be valid lowercase ENS labels. +- **What's public.** Anyone can look up any username and read every record you return. Return `404` for accounts that shouldn't be found. +- **Who keeps it running.** Your endpoint's uptime is the name's uptime. There's no fallback copy. +- **Who holds the parent name.** Whoever controls `brand.eth` can redirect every username. -## What this does not do +## What it doesn't do -- Your existing TLD does not become part of ENS. Users gain an ENS name; `.brand` stays yours. -- Support varies. Most major wallets resolve these names, but not every app does, so test the ones your users actually use. -- Anything served this way is public. Addresses, avatars, and profile fields are readable by anyone who asks. +- `.brand` doesn't become an ENS TLD. Users gain an ENS name alongside the username they have. +- Users don't own these names onchain. The name follows your system, so you can rename or remove it. +- Most major wallets follow CCIP-Read, but not every app does. Test the ones your users rely on. ## Next steps - - - Compare offchain and onchain names before you pick how to issue them. - - - Create names and manage their records with the Offchain Manager SDK. + + + The request, the response format and how to connect it. - Bring your existing naming service and we will map it onto ENS with you. + Bring your username system or naming service and we'll map it onto ENS with you. From a152a7e215776666203f5d7297c036402eb57d9a Mon Sep 17 00:00:00 2001 From: Harpreet Singh Date: Fri, 13 Nov 2026 18:36:41 +0530 Subject: [PATCH 2/7] docs: rewrite Universal Usernames guide as a three-step setup Prerequisites, build the adapter (schema, address keys, simple example), save it in the App, set the resolver. Adds security practices, pros and cons and an FAQ. Drops gateway internals and adapter testing. Co-Authored-By: Claude Opus 5.5 --- developer-guide/guide/universal-usernames.mdx | 270 ++++++++---------- 1 file changed, 120 insertions(+), 150 deletions(-) diff --git a/developer-guide/guide/universal-usernames.mdx b/developer-guide/guide/universal-usernames.mdx index 34d11b8..a0dce0b 100644 --- a/developer-guide/guide/universal-usernames.mdx +++ b/developer-guide/guide/universal-usernames.mdx @@ -1,43 +1,37 @@ --- -title: "Build a Universal Usernames endpoint" -description: "Serve ENS names for your users from the username system you already run." +title: "Set up Universal Usernames" +description: "Give every user in your app an ENS name by building one adapter endpoint." sidebarTitle: "Universal usernames" icon: "at" --- -This guide walks you through building the one endpoint Universal Usernames needs, then connecting it to your ENS name. When you're done, `happy` in your app resolves as `happy.brand.eth` in any ENS-aware wallet. +This guide gets `happy` in your app resolving as `happy.brand.eth` in any ENS-aware wallet. You build one endpoint, save it in the Namespace App and set your resolver. -The endpoint is a small HTTP service. It takes a username, reads that user from wherever your usernames live, and returns a profile in the format below. Where they live doesn't matter: a database behind your app, or a registry contract if you run a naming service. For why this works and what to decide first, read the [Universal usernames overview](/overview/universal-usernames). +To learn why this works and what it changes for your users, read the [Universal usernames overview](/overview/universal-usernames). ## Prerequisites -- An ENS name such as `brand.eth`, owned by a wallet you control. -- Somewhere to host a public HTTPS route. -- Usernames that are valid [ENSIP-15](https://docs.ens.domains/ensip/15) labels: lowercase, no dots. If yours allow uppercase, match against a lowercased copy. +- **An ENS name**, such as `brand.eth`, owned by a wallet you control. +- **An adapter.** A public HTTPS endpoint that reads a user from wherever your usernames live, such as your database, API or registry contract, and returns their profile. Step 1 covers it. -## Step 1: Build the endpoint +## Step 1: Build the adapter -### The request +### Request -You pick a base URL, such as `https://api.brand.example/ens`. For `happy.brand.eth`, the Namespace gateway sends: +You choose a base URL, such as `https://api.brand.example/ens`. For `happy.brand.eth`, Namespace calls: ```http -GET /ens/happy HTTP/1.1 -Host: api.brand.example -Accept: application/json -Accept-Encoding: identity +GET https://api.brand.example/ens/happy Authorization: Bearer YOUR_TOKEN ``` -- The last path segment is the username, URL-encoded and already normalized. Decode it before you look it up. -- `Authorization` is only sent if you save a bearer token in the App. -- Only single labels reach you. Nested names like `a.happy.brand.eth` never call your endpoint. +The last path segment is the username, lowercase and URL-encoded. The `Authorization` header is sent only if you save a bearer token in the App. We recommend one, so only Namespace can call your adapter. -### The response +### Response -Return `200` with this JSON for a user that exists, and `404` for one that doesn't: +Return `200` with the profile for a user that exists, and `404` for one that doesn't. -```json happy.json +```json { "version": 1, "username": "happy", @@ -55,185 +49,161 @@ Return `200` with this JSON for a user that exists, and `404` for one that doesn ``` - Always the number `1`. + Always `1`. - The requested username, exactly as it arrived after decoding. + The username from the request. - [ENSIP-5](https://docs.ens.domains/ensip/5) text records such as `name`, `avatar`, `description`, `url` and `com.twitter`. Use `{}` for none. + Profile fields. Use [ENSIP-5](https://docs.ens.domains/ensip/5) keys such as `name`, `avatar`, `description`, `url`, `email` and `com.twitter`. Use `{}` for none. - Addresses keyed by ENS coin type as a decimal string. Use `{}` for none. See [Address keys](#address-keys). + Wallet addresses keyed by coin type. Use `{}` for none. See [Format addresses](#format-addresses). - Optional. An `ipfs://`, `ipns://`, `ar://` or other [ENSIP-7](https://docs.ens.domains/ensip/7) URI. Leave it out when there is none. + Optional. A website for the user, as an `ipfs://`, `ipns://` or `ar://` URI. -Any other top-level field fails the profile. +Don't add other top-level fields. The profile fails if you do. -### Address keys +### Format addresses -- `2147483648` is the default EVM address. It answers for Ethereum and every EVM chain without its own key, so most users need only this one. -- Add `0x80000000 | chainId` for a chain where the address differs. Base (`8453`) is `2147492101`. viem's `toCoinType(chainId)` does the math. -- Non-EVM chains use their [SLIP-44](https://github.com/satoshilabs/slips/blob/master/slip-0044.md) number: Bitcoin is `0`, Solana is `501`. -- Return EVM addresses checksummed. Bitcoin addresses must be mainnet. +Each key in `addresses` is a coin type, written as a decimal string. It tells wallets which chain the address is for. -### Example endpoint +| Chain | Key | Why | +| --- | --- | --- | +| Every EVM chain (default) | `2147483648` | `0x80000000` in decimal, the ENS default EVM coin type | +| Ethereum mainnet | `60` | The [SLIP-44](https://github.com/satoshilabs/slips/blob/master/slip-0044.md) number for ETH | +| Base | `2147492101` | `0x80000000` plus Base's chain ID, `8453` | +| Bitcoin | `0` | SLIP-44 | +| Solana | `501` | SLIP-44 | -This route uses web-standard `Request` and `Response`, so it runs as a Next.js App Router route (`app/ens/[label]/route.ts`) or in any server that speaks Fetch. Swap `findUserByUsername` for your own lookup. +- **Most users need only `2147483648`.** It answers for Ethereum and every EVM chain that doesn't have its own key. +- **For a different address on one EVM chain**, add the key `0x80000000 | chainId`. viem's `toCoinType(chainId)` computes it for you. +- **For non-EVM chains**, use the chain's SLIP-44 number. -```ts route.ts -import { timingSafeEqual } from 'node:crypto'; -import { getAddress } from 'viem'; -import { findUserByUsername } from './users'; - -const BEARER_TOKEN = process.env.UUN_BEARER_TOKEN; -const DEFAULT_EVM_COIN_TYPE = '2147483648'; - -function isAuthorized(request: Request): boolean { - if (!BEARER_TOKEN) return true; - const expected = Buffer.from(`Bearer ${BEARER_TOKEN}`); - const received = Buffer.from(request.headers.get('authorization') ?? ''); - return ( - received.length === expected.length && timingSafeEqual(received, expected) - ); -} +Return EVM addresses in checksum format (viem's `getAddress` does this) and Bitcoin addresses in their mainnet form. Namespace encodes them for ENS, so you send plain address strings. -// GET {base URL}/{username} -export async function GET(request: Request): Promise { - if (!isAuthorized(request)) return new Response(null, { status: 401 }); +### Example adapter - const segment = new URL(request.url).pathname.split('/').pop() ?? ''; - let username: string; - try { - username = decodeURIComponent(segment); - } catch { - return new Response(null, { status: 404 }); +A Next.js route. Swap the database call for your own lookup. + +```ts app/ens/[username]/route.ts +import { getAddress } from 'viem'; +import { db } from '@/lib/db'; + +export async function GET( + request: Request, + { params }: { params: Promise<{ username: string }> }, +) { + const auth = request.headers.get('authorization'); + if (auth !== `Bearer ${process.env.ENS_ADAPTER_TOKEN}`) { + return new Response(null, { status: 401 }); } - const user = await findUserByUsername(username); - if (!user) return new Response(null, { status: 404 }); + const { username } = await params; + const user = await db.user.findUnique({ where: { username } }); + if (!user || !user.isPublic) { + return new Response(null, { status: 404 }); + } - // Anyone can read these, so publish only what the user chose to share. const texts: Record = {}; if (user.displayName) texts.name = user.displayName; if (user.avatarUrl) texts.avatar = user.avatarUrl; const addresses: Record = {}; if (user.walletAddress) { - addresses[DEFAULT_EVM_COIN_TYPE] = getAddress(user.walletAddress); + addresses['2147483648'] = getAddress(user.walletAddress); } return Response.json({ version: 1, username, texts, addresses }); } ``` -```ts users.ts -export type User = { - displayName?: string; - avatarUrl?: string; - walletAddress?: string; -}; - -// Replace with a query against your users table. -export async function findUserByUsername(username: string): Promise { - throw new Error(`findUserByUsername is not implemented: ${username}`); -} -``` - -### If your usernames live onchain - -Running a naming service with its own registry? Keep the same route and read the user from your contract instead. This version of `findUserByUsername` reads the address with viem. Replace the ABI and function with your registry's own lookup. - -```ts users.ts -import { createPublicClient, http, parseAbi, zeroAddress } from 'viem'; - -const client = createPublicClient({ transport: http(process.env.RPC_URL) }); - -const REGISTRY_ADDRESS = process.env.REGISTRY_ADDRESS as `0x${string}`; -const REGISTRY_ABI = parseAbi([ - 'function resolve(string name) view returns (address)', -]); - -export type User = { - displayName?: string; - avatarUrl?: string; - walletAddress?: string; -}; - -export async function findUserByUsername(username: string): Promise { - const walletAddress = await client.readContract({ - address: REGISTRY_ADDRESS, - abi: REGISTRY_ABI, - functionName: 'resolve', - args: [username], - }); - if (walletAddress === zeroAddress) return null; - return { walletAddress }; -} -``` - -Every lookup hits your RPC, so use a reliable provider. The gateway caches each profile for 60 seconds. - -### Test it - -```bash -curl -i https://api.brand.example/ens/happy -H 'Authorization: Bearer YOUR_TOKEN' -``` +If your usernames live onchain, keep the same route and read the address from your registry contract instead of the database. -Expect `200`, `content-type: application/json` and `"username": "happy"`. An unknown username should return `404`. + +**Adapter requirements.** HTTPS with a valid certificate, `application/json`, uncompressed, under 256 KiB, and a reply within 5 seconds. Redirects, `401`, `403`, `429` and `5xx` responses fail the lookup. Only `404` means the user doesn't exist. + -### Rules the gateway enforces - -The gateway fails the lookup instead of guessing, so check these before you go live: - -- The base URL is `https://`, with no query string or fragment, up to 2048 characters. -- The host resolves to public IPs only and has a valid TLS certificate. -- The response is `application/json`, uncompressed, at most 256 KiB, and arrives within 5 seconds. -- Redirects, `401`, `403`, `429` and `5xx` all fail the lookup. Only `404` means "no such user". -- At most 128 text records and 128 addresses. - -## Step 2: Connect it in the Namespace App +## Step 2: Save the adapter in the Namespace App - - Open [Universal Usernames](https://app.namespace.ninja/universal-usernames), connect the wallet that owns `brand.eth`, and enter your base URL and optional bearer token. + + Go to [Universal Usernames](https://app.namespace.ninja/universal-usernames), connect the wallet that owns `brand.eth` and select the name. - - Enter a real username and select **Check endpoint**. The check runs in your browser, so allow `https://app.namespace.ninja` with CORS (plus `Access-Control-Allow-Headers: Authorization` if you use a token). It's optional. + + Enter your base URL and, if you use one, your bearer token. Select **Save endpoint**. - - Send the transaction the App shows. When it reads **Resolver set and configured**, every `username.brand.eth` resolves from your endpoint. + + Enter a username that exists in your app and select **Test username**. The App shows what your adapter returned. -A name serves one kind of subname at a time. If `brand.eth` already serves offchain or L2 subnames, those stop resolving once you switch. +The test runs from your browser, so it shows **Blocked by CORS or unreachable** unless your adapter allows `https://app.namespace.ninja` (plus the `Authorization` header if you use a token). Real lookups come from the Namespace server, so CORS doesn't affect resolution. You can skip the test. -Profile changes reach wallets within 60 seconds. A new endpoint or token takes effect within about 5 seconds. - -## Before you go live +## Step 3: Set the resolver -Your endpoint now decides where payments to your users go. +Below your saved endpoint, the App walks you through up to three transactions: -- Return `404` for private, suspended or deleted accounts. Anyone can guess usernames. -- Serve only addresses the user has proven they control. -- Don't hand a released username to someone new right away, or payments meant for the old user go to them. -- Require a bearer token, and keep the wallet that owns `brand.eth` on a hardware wallet or multisig. + + + Copies the records `brand.eth` has today, such as its address and avatar, to the new resolver so they keep resolving. + + + Points `brand.eth` at the Namespace resolver. + + + Routes every subname of `brand.eth` to your adapter. The step reads **Resolver set and configured** when you're done. + + -## Next steps + +A name serves one kind of subname at a time. If `brand.eth` already has offchain or L2 subnames, they stop resolving once you enable Universal Usernames. + - - - Why it works and what to decide before you build. - - - Save your endpoint and set the resolver. - - +That's it. `happy.brand.eth` now resolves with any ENS-compatible library or wallet, such as viem, ethers or wagmi, with no extra setup. + +## Security practices + +Your adapter decides where payments to your users go, so treat it like a payments API. + +- **Use a bearer token** so only Namespace can call your adapter. +- **Return `404` for private, suspended or deleted accounts.** Anyone can guess a username and look it up. +- **Serve only addresses the user has proven they control**, for example by signing a message. +- **Don't reassign a released username right away.** Payments meant for the old user would go to the new one. +- **Protect the wallet that owns `brand.eth`** with a hardware wallet or multisig. Whoever controls it can redirect every username. + +## Pros and cons + +| Pros | Cons | +| --- | --- | +| Every existing user gets an ENS name at once, with nothing to mint | Users don't own the names onchain. Your system can rename or remove them | +| Your database stays the source of truth, with no syncing | If your adapter is down, names stop resolving. There's no fallback copy | +| No gas per user. Setup takes a few transactions on one name | A few apps don't support offchain (CCIP-Read) resolution yet | + +## FAQ + + + + Only what your adapter returns. If people already see usernames, display names and avatars in your app, that data is public anyway. Exposing it through ENS doesn't change that. Leave out anything a user hasn't chosen to share. + + + Within 60 seconds. Namespace caches each profile for that long. + + + Yes. The adapter can read from a registry contract or an indexer instead of a database. The response format is the same. + + + ENS names are lowercase, and each username has to be a single label. Look users up by a lowercased copy of their username. Usernames with dots won't resolve. + + + Yes. Point `brand.eth` at a different resolver at any time. Universal Usernames subnames stop resolving when you do. + + From 066d9572b1a5b58295f74534984c538fc8c54ee2 Mon Sep 17 00:00:00 2001 From: Harpreet Singh Date: Fri, 13 Nov 2026 18:36:51 +0530 Subject: [PATCH 3/7] docs: reject requests when the adapter token is unset Co-Authored-By: Claude Opus 5.5 --- developer-guide/guide/universal-usernames.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/developer-guide/guide/universal-usernames.mdx b/developer-guide/guide/universal-usernames.mdx index a0dce0b..768e941 100644 --- a/developer-guide/guide/universal-usernames.mdx +++ b/developer-guide/guide/universal-usernames.mdx @@ -100,8 +100,9 @@ export async function GET( request: Request, { params }: { params: Promise<{ username: string }> }, ) { + const token = process.env.ENS_ADAPTER_TOKEN; const auth = request.headers.get('authorization'); - if (auth !== `Bearer ${process.env.ENS_ADAPTER_TOKEN}`) { + if (!token || auth !== `Bearer ${token}`) { return new Response(null, { status: 401 }); } From 8da671107e440348ce7c6efd650620fb4075e965 Mon Sep 17 00:00:00 2001 From: Harpreet Singh Date: Fri, 13 Nov 2026 22:40:50 +0530 Subject: [PATCH 4/7] docs: add ENSIP-15 username rules to the Universal Usernames guide Co-Authored-By: Claude Opus 5.5 --- developer-guide/guide/universal-usernames.mdx | 43 +++++++++++++++++-- 1 file changed, 39 insertions(+), 4 deletions(-) diff --git a/developer-guide/guide/universal-usernames.mdx b/developer-guide/guide/universal-usernames.mdx index 768e941..d2c301e 100644 --- a/developer-guide/guide/universal-usernames.mdx +++ b/developer-guide/guide/universal-usernames.mdx @@ -13,6 +13,40 @@ To learn why this works and what it changes for your users, read the [Universal - **An ENS name**, such as `brand.eth`, owned by a wallet you control. - **An adapter.** A public HTTPS endpoint that reads a user from wherever your usernames live, such as your database, API or registry contract, and returns their profile. Step 1 covers it. +- **Usernames that are valid ENS labels.** See [Username rules](#username-rules). + +## Username rules + +Each username becomes one ENS label, so it must pass [ENSIP-15](https://docs.ens.domains/ensip/15) normalization. Wallets normalize a name before they look it up, so your adapter always receives the normalized form. + +| Username | ENS label | Result | +| --- | --- | --- | +| `happy`, `happy-doe`, `123` | Same | Works | +| `Happy`, `HAPPY` | `happy` | Works, but lowercased | +| `héllo`, `😀` | Same | Works. Other scripts and emoji are valid | +| `_happy` | Same | Works. Underscores are allowed only at the start | +| `happy_doe` | None | Invalid | +| `happy.doe` | None | Never reaches your adapter. A dot splits it into two labels | +| `happy doe`, `@happy`, `happy!`, `happy+1` | None | Invalid. Spaces and most punctuation are disallowed | +| `ab--cd` | None | Invalid. No `--` in the third and fourth characters | + +Normalization also rewrites some characters, such as `'` to `’`, and removes invisible ones. So don't compare the raw username. Store a normalized copy next to each username and look users up by that: + +```ts +import { normalize } from 'viem/ens'; + +// Returns the ENS label for a username, or null if it can't be one. +export function toEnsLabel(username: string): string | null { + try { + const label = normalize(username); + return label && !label.includes('.') ? label : null; + } catch { + return null; + } +} +``` + +Users whose username returns `null` can't get an ENS name. If you're designing usernames from scratch, allow only `a-z`, `0-9` and `-` and every username will work. ## Step 1: Build the adapter @@ -25,7 +59,7 @@ GET https://api.brand.example/ens/happy Authorization: Bearer YOUR_TOKEN ``` -The last path segment is the username, lowercase and URL-encoded. The `Authorization` header is sent only if you save a bearer token in the App. We recommend one, so only Namespace can call your adapter. +The last path segment is the username, normalized and URL-encoded. The `Authorization` header is sent only if you save a bearer token in the App. We recommend one, so only Namespace can call your adapter. ### Response @@ -107,7 +141,8 @@ export async function GET( } const { username } = await params; - const user = await db.user.findUnique({ where: { username } }); + // ensLabel is the normalized copy from toEnsLabel. + const user = await db.user.findUnique({ where: { ensLabel: username } }); if (!user || !user.isPublic) { return new Response(null, { status: 404 }); } @@ -201,8 +236,8 @@ Your adapter decides where payments to your users go, so treat it like a payment Yes. The adapter can read from a registry contract or an indexer instead of a database. The response format is the same. - - ENS names are lowercase, and each username has to be a single label. Look users up by a lowercased copy of their username. Usernames with dots won't resolve. + + They don't get an ENS name. The rest of your users still do. See [Username rules](#username-rules) for what's valid. Yes. Point `brand.eth` at a different resolver at any time. Universal Usernames subnames stop resolving when you do. From 4e359c909c44a789759cccd2d4fd17ae3408e506 Mon Sep 17 00:00:00 2001 From: Harpreet Singh Date: Fri, 13 Nov 2026 23:39:29 +0530 Subject: [PATCH 5/7] docs: reframe Universal Usernames guide as three steps Open with the three steps instead of prerequisites, move username, text record and address formats under the endpoint step, document custom text keys, drop pros and cons, and point the overview's next steps at the setup guide and the App. Co-Authored-By: Claude Opus 5.5 --- developer-guide/guide/universal-usernames.mdx | 171 +++++++++--------- overview/universal-usernames.mdx | 8 +- 2 files changed, 90 insertions(+), 89 deletions(-) diff --git a/developer-guide/guide/universal-usernames.mdx b/developer-guide/guide/universal-usernames.mdx index d2c301e..aaffdeb 100644 --- a/developer-guide/guide/universal-usernames.mdx +++ b/developer-guide/guide/universal-usernames.mdx @@ -1,69 +1,40 @@ --- title: "Set up Universal Usernames" -description: "Give every user in your app an ENS name by building one adapter endpoint." +description: "Make your in-app usernames work outside your app, as ENS names." sidebarTitle: "Universal usernames" icon: "at" --- -This guide gets `happy` in your app resolving as `happy.brand.eth` in any ENS-aware wallet. You build one endpoint, save it in the Namespace App and set your resolver. +This guide makes your in-app usernames universal, so `happy` in your app becomes `happy.brand.eth` everywhere else. All you need is an ENS name. Setup takes three steps: -To learn why this works and what it changes for your users, read the [Universal usernames overview](/overview/universal-usernames). +1. Build an API endpoint that returns a user's profile from your own data. +2. Save the endpoint in the Namespace App. +3. Set the resolver on your ENS name. -## Prerequisites +Your users don't sign up, mint or move anything. Every valid username you've issued works as soon as the resolver is set. -- **An ENS name**, such as `brand.eth`, owned by a wallet you control. -- **An adapter.** A public HTTPS endpoint that reads a user from wherever your usernames live, such as your database, API or registry contract, and returns their profile. Step 1 covers it. -- **Usernames that are valid ENS labels.** See [Username rules](#username-rules). + + Why it works, and what it changes for your users. + -## Username rules +## Step 1: Build the API endpoint -Each username becomes one ENS label, so it must pass [ENSIP-15](https://docs.ens.domains/ensip/15) normalization. Wallets normalize a name before they look it up, so your adapter always receives the normalized form. - -| Username | ENS label | Result | -| --- | --- | --- | -| `happy`, `happy-doe`, `123` | Same | Works | -| `Happy`, `HAPPY` | `happy` | Works, but lowercased | -| `héllo`, `😀` | Same | Works. Other scripts and emoji are valid | -| `_happy` | Same | Works. Underscores are allowed only at the start | -| `happy_doe` | None | Invalid | -| `happy.doe` | None | Never reaches your adapter. A dot splits it into two labels | -| `happy doe`, `@happy`, `happy!`, `happy+1` | None | Invalid. Spaces and most punctuation are disallowed | -| `ab--cd` | None | Invalid. No `--` in the third and fourth characters | - -Normalization also rewrites some characters, such as `'` to `’`, and removes invisible ones. So don't compare the raw username. Store a normalized copy next to each username and look users up by that: - -```ts -import { normalize } from 'viem/ens'; - -// Returns the ENS label for a username, or null if it can't be one. -export function toEnsLabel(username: string): string | null { - try { - const label = normalize(username); - return label && !label.includes('.') ? label : null; - } catch { - return null; - } -} -``` - -Users whose username returns `null` can't get an ENS name. If you're designing usernames from scratch, allow only `a-z`, `0-9` and `-` and every username will work. - -## Step 1: Build the adapter +The endpoint takes a username, reads that user from wherever your usernames live, such as a database, an API or a registry contract, and returns their public profile. ### Request -You choose a base URL, such as `https://api.brand.example/ens`. For `happy.brand.eth`, Namespace calls: +You choose a base URL, such as `https://api.brand.example/ens`. When someone looks up `happy.brand.eth`, your endpoint gets: ```http GET https://api.brand.example/ens/happy Authorization: Bearer YOUR_TOKEN ``` -The last path segment is the username, normalized and URL-encoded. The `Authorization` header is sent only if you save a bearer token in the App. We recommend one, so only Namespace can call your adapter. +The last path segment is the username, normalized and URL-encoded. The `Authorization` header is sent only if you save a bearer token in step 2. We recommend one, so nobody else can call your endpoint. ### Response -Return `200` with the profile for a user that exists, and `404` for one that doesn't. +Return `200` with the user's profile, or `404` if the user doesn't exist. ```json { @@ -82,31 +53,69 @@ Return `200` with the profile for a user that exists, and `404` for one that doe } ``` - - Always `1`. - +| Field | Value | +| --- | --- | +| `version` | Always `1`. | +| `username` | The username from the request. | +| `texts` | Profile fields, as strings. See [Text records](#text-records). Use `{}` for none. | +| `addresses` | Wallet addresses by coin type. See [Addresses](#addresses). Use `{}` for none. | +| `contenthash` | Optional. A website for the user, such as `ipfs://…` or `ar://…`. | - - The username from the request. - +Don't add other top-level fields. The profile fails if you do. - - Profile fields. Use [ENSIP-5](https://docs.ens.domains/ensip/5) keys such as `name`, `avatar`, `description`, `url`, `email` and `com.twitter`. Use `{}` for none. - +Before you write the endpoint, check that your usernames, text records and addresses fit the format below. - - Wallet addresses keyed by coin type. Use `{}` for none. See [Format addresses](#format-addresses). - +### Usernames - - Optional. A website for the user, as an `ipfs://`, `ipns://` or `ar://` URI. - +Each username becomes one ENS label, so it must pass [ENSIP-15](https://docs.ens.domains/ensip/15) normalization. Wallets normalize a name before looking it up, so your endpoint always receives the normalized form. -Don't add other top-level fields. The profile fails if you do. +| Username | Result | +| --- | --- | +| `happy`, `happy-doe`, `123` | Works as is | +| `Happy`, `HAPPY` | Works, as `happy` | +| `héllo`, `😀` | Works. Other scripts and emoji are valid | +| `_happy` | Works. Underscores are allowed only at the start | +| `happy_doe` | Invalid | +| `happy.doe` | Never reaches your endpoint. A dot splits it into two labels | +| `happy doe`, `@happy`, `happy!`, `happy+1` | Invalid. Spaces and most punctuation are disallowed | +| `ab--cd` | Invalid. No `--` in the third and fourth characters | -### Format addresses +Normalization also rewrites some characters, such as `'` to `’`, and removes invisible ones. Store a normalized copy next to each username and look users up by that copy: -Each key in `addresses` is a coin type, written as a decimal string. It tells wallets which chain the address is for. +```ts +import { normalize } from 'viem/ens'; + +// Returns the ENS label for a username, or null if it can't be one. +export function toEnsLabel(username: string): string | null { + try { + const label = normalize(username); + return label && !label.includes('.') ? label : null; + } catch { + return null; + } +} +``` + +Users whose username returns `null` don't get an ENS name. If you're designing usernames from scratch, allowing only `a-z`, `0-9` and `-` means every username works. + +### Text records + +`texts` holds everything that isn't an address. Use the standard [ENSIP-5](https://docs.ens.domains/ensip/5) keys where they fit, since wallets and apps know how to show them: + +| Key | Value | +| --- | --- | +| `name` | Display name | +| `avatar` | Image URL (`https://`, `ipfs://`) or an NFT as `eip155:1/erc721:0x…/1` | +| `description` | Short bio | +| `url` | Website | +| `email` | Email address | +| `com.twitter`, `com.github`, `org.telegram` | Handle on that service | + +You can add your own keys too. Prefix them with your domain, such as `com.brand.tier` or `com.brand.member-since`, so they don't collide with anyone else's. Every value is a string, and a profile holds up to 128 text records. + +### Addresses + +Each key in `addresses` is a coin type, written as a decimal string. It tells wallets which chain the address belongs to. | Chain | Key | Why | | --- | --- | --- | @@ -120,9 +129,9 @@ Each key in `addresses` is a coin type, written as a decimal string. It tells wa - **For a different address on one EVM chain**, add the key `0x80000000 | chainId`. viem's `toCoinType(chainId)` computes it for you. - **For non-EVM chains**, use the chain's SLIP-44 number. -Return EVM addresses in checksum format (viem's `getAddress` does this) and Bitcoin addresses in their mainnet form. Namespace encodes them for ENS, so you send plain address strings. +Send plain address strings, not encoded bytes. EVM addresses go in checksum format (viem's `getAddress`), and Bitcoin addresses in their mainnet form. -### Example adapter +### Example endpoint A Next.js route. Swap the database call for your own lookup. @@ -160,13 +169,13 @@ export async function GET( } ``` -If your usernames live onchain, keep the same route and read the address from your registry contract instead of the database. +If your usernames live onchain, keep the same route and read from your registry contract instead of the database. -**Adapter requirements.** HTTPS with a valid certificate, `application/json`, uncompressed, under 256 KiB, and a reply within 5 seconds. Redirects, `401`, `403`, `429` and `5xx` responses fail the lookup. Only `404` means the user doesn't exist. +The endpoint must use HTTPS with a valid certificate, return uncompressed `application/json` under 256 KiB, and reply within 5 seconds. Redirects, `401`, `403`, `429` and `5xx` responses fail the lookup. Only `404` means the user doesn't exist. -## Step 2: Save the adapter in the Namespace App +## Step 2: Save the endpoint in the Namespace App @@ -176,17 +185,17 @@ If your usernames live onchain, keep the same route and read the address from yo Enter your base URL and, if you use one, your bearer token. Select **Save endpoint**. - Enter a username that exists in your app and select **Test username**. The App shows what your adapter returned. + Enter a username that exists in your app and select **Test username**. The App shows what your endpoint returned. -The test runs from your browser, so it shows **Blocked by CORS or unreachable** unless your adapter allows `https://app.namespace.ninja` (plus the `Authorization` header if you use a token). Real lookups come from the Namespace server, so CORS doesn't affect resolution. You can skip the test. +The test runs from your browser, so it shows **Blocked by CORS or unreachable** unless your endpoint allows `https://app.namespace.ninja` (plus the `Authorization` header if you use a token). Real lookups don't come from a browser, so CORS doesn't affect resolution. You can skip the test. ## Step 3: Set the resolver -Below your saved endpoint, the App walks you through up to three transactions: +This is the step that makes your usernames live. Below your saved endpoint, the App walks you through up to three transactions: @@ -196,7 +205,7 @@ Below your saved endpoint, the App walks you through up to three transactions: Points `brand.eth` at the Namespace resolver. - Routes every subname of `brand.eth` to your adapter. The step reads **Resolver set and configured** when you're done. + Routes every subname of `brand.eth` to your endpoint. The step reads **Resolver set and configured** when you're done. @@ -204,40 +213,32 @@ Below your saved endpoint, the App walks you through up to three transactions: A name serves one kind of subname at a time. If `brand.eth` already has offchain or L2 subnames, they stop resolving once you enable Universal Usernames. -That's it. `happy.brand.eth` now resolves with any ENS-compatible library or wallet, such as viem, ethers or wagmi, with no extra setup. +That's it. `happy.brand.eth` now resolves outside your app, in any wallet or library that supports ENS, such as viem, ethers or wagmi. ## Security practices -Your adapter decides where payments to your users go, so treat it like a payments API. +Your endpoint decides where payments to your users go, so treat it like a payments API. -- **Use a bearer token** so only Namespace can call your adapter. +- **Use a bearer token** so nobody else can call your endpoint. - **Return `404` for private, suspended or deleted accounts.** Anyone can guess a username and look it up. - **Serve only addresses the user has proven they control**, for example by signing a message. - **Don't reassign a released username right away.** Payments meant for the old user would go to the new one. - **Protect the wallet that owns `brand.eth`** with a hardware wallet or multisig. Whoever controls it can redirect every username. -## Pros and cons - -| Pros | Cons | -| --- | --- | -| Every existing user gets an ENS name at once, with nothing to mint | Users don't own the names onchain. Your system can rename or remove them | -| Your database stays the source of truth, with no syncing | If your adapter is down, names stop resolving. There's no fallback copy | -| No gas per user. Setup takes a few transactions on one name | A few apps don't support offchain (CCIP-Read) resolution yet | - ## FAQ - Only what your adapter returns. If people already see usernames, display names and avatars in your app, that data is public anyway. Exposing it through ENS doesn't change that. Leave out anything a user hasn't chosen to share. + Only what your endpoint returns. If people already see usernames, display names and avatars in your app, that data is public anyway, and showing it through ENS doesn't change that. Leave out anything a user hasn't chosen to share. - Within 60 seconds. Namespace caches each profile for that long. + Usually right away. A profile is cached for at most a minute, so an edit can take up to that long to reach wallets. - Yes. The adapter can read from a registry contract or an indexer instead of a database. The response format is the same. + Yes. The endpoint can read from a registry contract or an indexer instead of a database. The response format is the same. - They don't get an ENS name. The rest of your users still do. See [Username rules](#username-rules) for what's valid. + They don't get an ENS name. The rest of your users still do. See [Usernames](#usernames) for what's valid. Yes. Point `brand.eth` at a different resolver at any time. Universal Usernames subnames stop resolving when you do. diff --git a/overview/universal-usernames.mdx b/overview/universal-usernames.mdx index 73ae970..330ad18 100644 --- a/overview/universal-usernames.mdx +++ b/overview/universal-usernames.mdx @@ -51,10 +51,10 @@ The endpoint reads from wherever your usernames live. A neobank, wallet or payme ## Next steps - - The request, the response format and how to connect it. + + Build one endpoint, save it and set your resolver. Three steps, no migration. - - Bring your username system or naming service and we'll map it onto ENS with you. + + Connect your ENS name and go live yourself, with the endpoint format and an AI prompt to build it. From 5072c03caa168f7702f575f08755f3528afd6527 Mon Sep 17 00:00:00 2001 From: Harpreet Singh Date: Sat, 14 Nov 2026 00:02:14 +0530 Subject: [PATCH 6/7] docs: clarify the endpoint URL and cover ENSIP-18 text keys Show the request as {base URL}/{username} without a /ens path, add ENSIP-18 profile keys and a custom key to the text record table. Co-Authored-By: Claude Opus 5.5 --- developer-guide/guide/universal-usernames.mdx | 47 ++++++++++++------- 1 file changed, 29 insertions(+), 18 deletions(-) diff --git a/developer-guide/guide/universal-usernames.mdx b/developer-guide/guide/universal-usernames.mdx index aaffdeb..8f41288 100644 --- a/developer-guide/guide/universal-usernames.mdx +++ b/developer-guide/guide/universal-usernames.mdx @@ -23,14 +23,20 @@ The endpoint takes a username, reads that user from wherever your usernames live ### Request -You choose a base URL, such as `https://api.brand.example/ens`. When someone looks up `happy.brand.eth`, your endpoint gets: +You choose a base URL, such as `https://api.brand.example`. Each lookup adds the username to the end of it: ```http -GET https://api.brand.example/ens/happy +GET {base URL}/{username} +``` + +So when someone looks up `happy.brand.eth`, your endpoint gets: + +```http +GET https://api.brand.example/happy Authorization: Bearer YOUR_TOKEN ``` -The last path segment is the username, normalized and URL-encoded. The `Authorization` header is sent only if you save a bearer token in step 2. We recommend one, so nobody else can call your endpoint. +The username arrives normalized and URL-encoded. Your base URL can include a path, such as `https://brand.example/api/ens`, if the endpoint lives inside an existing app. The `Authorization` header is sent only if you save a bearer token in step 2. We recommend one, so nobody else can call your endpoint. ### Response @@ -42,8 +48,10 @@ Return `200` with the user's profile, or `404` if the user doesn't exist. "username": "happy", "texts": { "name": "Happy", + "alias": "Happy", "avatar": "https://cdn.brand.example/avatars/happy.png", - "com.twitter": "happy" + "com.twitter": "happy", + "com.brand.tier": "gold" }, "addresses": { "2147483648": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", @@ -100,18 +108,21 @@ Users whose username returns `null` don't get an ENS name. If you're designing u ### Text records -`texts` holds everything that isn't an address. Use the standard [ENSIP-5](https://docs.ens.domains/ensip/5) keys where they fit, since wallets and apps know how to show them: +`texts` holds everything that isn't an address. Use the standard keys where they fit, since wallets and apps know how to show them. [ENSIP-5](https://docs.ens.domains/ensip/5) defines the base keys, and [ENSIP-18](https://docs.ens.domains/ensip/18) adds profile keys on top. -| Key | Value | -| --- | --- | -| `name` | Display name | -| `avatar` | Image URL (`https://`, `ipfs://`) or an NFT as `eip155:1/erc721:0x…/1` | -| `description` | Short bio | -| `url` | Website | -| `email` | Email address | -| `com.twitter`, `com.github`, `org.telegram` | Handle on that service | - -You can add your own keys too. Prefix them with your domain, such as `com.brand.tier` or `com.brand.member-since`, so they don't collide with anyone else's. Every value is a string, and a profile holds up to 128 text records. +| Key | Value | Spec | +| --- | --- | --- | +| `name`, `alias` | Display name. ENSIP-18 renames `name` to `alias`, but many apps still read `name`, so set both | ENSIP-18 | +| `avatar` | Image URL (`https://`, `ipfs://`) or an NFT as `eip155:1/erc721:0x…/1`. See [ENSIP-12](https://docs.ens.domains/ensip/12) | ENSIP-5 | +| `header` | Banner image, same format as `avatar` | ENSIP-18 | +| `description` | Short bio | ENSIP-5 | +| `url` | Website | ENSIP-5 | +| `email` | Email address | ENSIP-5 | +| `location`, `timezone` | Where the user is, such as `Berlin, Germany` and `Europe/Berlin` | ENSIP-5, ENSIP-18 | +| `com.twitter`, `com.github`, `org.telegram` | Handle on that service, without `@` | ENSIP-5 | +| `com.brand.tier` | Your own data. Any key you prefix with your domain | Custom | + +Custom keys use reverse-domain notation, such as `com.brand.tier` or `com.brand.member-since`, so they never collide with anyone else's. Every value is a string, and a profile holds up to 128 text records. ### Addresses @@ -133,9 +144,9 @@ Send plain address strings, not encoded bytes. EVM addresses go in checksum form ### Example endpoint -A Next.js route. Swap the database call for your own lookup. +A Next.js route, deployed at your base URL. Swap the database call for your own lookup. -```ts app/ens/[username]/route.ts +```ts app/[username]/route.ts import { getAddress } from 'viem'; import { db } from '@/lib/db'; @@ -157,7 +168,7 @@ export async function GET( } const texts: Record = {}; - if (user.displayName) texts.name = user.displayName; + if (user.displayName) texts.name = texts.alias = user.displayName; if (user.avatarUrl) texts.avatar = user.avatarUrl; const addresses: Record = {}; From 04953a304587a8e1790f83fa1f3380a0b9a6c663 Mon Sep 17 00:00:00 2001 From: Harpreet Singh Date: Sat, 14 Nov 2026 00:08:30 +0530 Subject: [PATCH 7/7] docs: drop the leftover /ens path from the request section Co-Authored-By: Claude Opus 5.5 --- developer-guide/guide/universal-usernames.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/developer-guide/guide/universal-usernames.mdx b/developer-guide/guide/universal-usernames.mdx index 8f41288..7ff8e19 100644 --- a/developer-guide/guide/universal-usernames.mdx +++ b/developer-guide/guide/universal-usernames.mdx @@ -29,14 +29,14 @@ You choose a base URL, such as `https://api.brand.example`. Each lookup adds the GET {base URL}/{username} ``` -So when someone looks up `happy.brand.eth`, your endpoint gets: +So for the username `happy`, the request is: ```http GET https://api.brand.example/happy Authorization: Bearer YOUR_TOKEN ``` -The username arrives normalized and URL-encoded. Your base URL can include a path, such as `https://brand.example/api/ens`, if the endpoint lives inside an existing app. The `Authorization` header is sent only if you save a bearer token in step 2. We recommend one, so nobody else can call your endpoint. +The username arrives normalized and URL-encoded. The `Authorization` header is sent only if you save a bearer token in step 2. We recommend one, so nobody else can call your endpoint. ### Response