Onchain names on a phone: what resolves
What a phone user can do with an onchain name in a wallet app, why the phone browser does not open it, how to test on devices and how to word the mention.
Your customers will meet your name on a phone. They will see pay.yourbrand on a checkout screen, in a message from your support team or on a printed card, and the first thing many of them will do is tap it or type it into whatever is open in their hand. What happens next depends on which app receives those characters, and on a phone that question has a narrower answer than on a desk.
An onchain name is a name recorded on a blockchain by a naming registry instead of in the internet’s domain name system. An onchain TLD is the suffix, such as .yourbrand, recorded as a token held in a wallet, and its holder issues the names beneath it. Software that knows how to read the registry can turn the name into a payment address or into the location of a website. Software that does not know simply sees a string with a dot in it.
This article is written for the brand or product lead who owns the customer experience and has to decide where the name may appear. It covers what a phone user can do with a name inside a wallet app that supports it, why the phone’s ordinary browser does not open it, how to test on real devices before you publish, and how to word the public mention so that it stays true.
Why the browser on a phone does not open an onchain name
A phone browser opens a web address by asking a DNS resolver, usually the one supplied by the mobile carrier or the Wi-Fi network, where the name lives. That resolver works its way down from the DNS root, the top of the domain name system that ICANN coordinates, through the registry of the suffix, to the server that holds the answer. Every step assumes that the suffix exists in the DNS root.
An onchain TLD is not in the DNS root. It lives on a blockchain, in a registry contract, and nothing in the path from the phone to the carrier’s resolver knows to look there. So the resolver answers, correctly from its point of view, that no such domain exists. The browser has nothing to load.
An ordinary browser opens such a name only when something has been added to it that knows where to look. On a desktop, that something can be a browser extension: Freename names open in desktop browsers through the Freename Web3 extension. The fact is about desktop browsers, and you should read it that narrowly. A phone browser is not the same software as its desktop counterpart, and you should not assume that an add-on which works on a laptop has an equivalent on the phones your customers carry. Treat the phone’s ordinary browser as a place where your onchain name does not resolve, and plan from there.
What a phone does with a name it cannot resolve
The failure is rarely a clean error page, which is why it is worth knowing its shapes before a customer describes one to your support team.
The address bar turns the name into a search
On most phones the address bar and the search box are the same field. The browser decides whether the typed text is an address or a query, and one of the signals it uses is whether the ending looks like a suffix it knows. pay.yourbrand does not end in one. The usual result is a page of search results for the words “pay” and “yourbrand”, and the customer has now left your journey for a results page you do not control. Whatever ranks there, good or bad, is what they see next.
Messaging apps do not make it tappable
Messaging and email apps turn text into a link when they recognize it as a web address. A name on an unfamiliar suffix is often left as plain text. That is a small thing, but it changes behavior: a customer who cannot tap will copy, and a customer who copies on a phone often pastes into the browser, which leads back to the search page above.
The camera reads a code as text
A printed code can carry any text. If it carries a web address in the DNS, the phone’s camera offers to open it. If it carries only pay.yourbrand, the camera has a string it does not know how to act on, and it will show it, search it or do nothing, depending on the device. What a wallet app’s own scanner does with the same code is a separate question, and one for the test described further down.
Each of these outcomes is a dead end at the moment a customer has decided to pay or to read. The remedy is to send the name only to places where it works.
Where phone support sits: the wallet app
On a phone, the software that understands an onchain name is the wallet app. A wallet is the application that holds a person’s keys and prepares transactions for them to approve. When a wallet supports a naming registry, it carries the logic the browser lacks: given a name, it queries the registry’s resolver, the contract or service that returns the records attached to that name, and gets back an address.
Two wallets are documented as supporting Freename names: Bitcoin.com Wallet, and MetaMask by way of Freename’s resolver. Those are the two wallet facts this article relies on, and it relies on nothing beyond them. Which version of which app on which operating system resolves which name is not something to take from an article. Coverage is partial, it changes as wallets release updates, and the only reliable statement about a given phone is the one you obtain by holding that phone. The page on names that resolve in wallets describes the capability, and the record of what is live keeps the sources together.
The practical consequence for a product lead is a change of mental model. On the DNS, a name works everywhere and you design for everyone. Onchain, a name works inside specific apps and you design for the people who have one of them open. The table sets out what such a person can generally do, and where the limits are.
| What the user wants | Inside a supporting wallet app | Limit to keep in mind |
|---|---|---|
| Send to you | Enters the name in the recipient field; the app resolves it to an address | Only for the networks the name has records for |
| Check before sending | Sees the resolved address next to the name | The user must look; the app does not judge intent |
| Receive from others | Gives out a name they hold instead of a long address | The sender’s app must support the name too |
| Save a contact | Stores the name or the resolved address | A stored address does not follow a later record change |
| Open a site on the name | Depends on whether the app includes a browser that resolves it | Test it; never assume it |
Two rows deserve a comment. The first is the one that matters most to a brand: replacing a long string of characters with pay.yourbrand in the recipient field removes the step where customers make copying errors and where they have no way to tell one address from another by eye. The last row is the weakest. Some wallet apps include a browser of their own, and whether that browser opens a website published on an onchain name is a matter of the app and its version. A website is therefore the use you should promise least on a phone.
A name can also carry a different record for each blockchain, and a wallet resolves the record for the network the user is sending on. If that record is empty, the app has no address to send to, and what the customer sees at that point is for your test to establish. Setting the records for every network you intend to accept is part of publishing the name.
One more limit belongs here. The wallet shows what the name resolves to, not who stands behind it. Saying which name is yours is a job for your own channels, and the section on wording returns to it.
Mapping your customer journeys to the screen they happen on
Before testing anything, write down the moments at which a customer would meet the name, and for each one, the app that is open on the phone at that moment. This is quick, and it usually removes half the planned uses without any device being touched.
| Moment | App open on the phone | Does the name belong there |
|---|---|---|
| Paying an invoice from a wallet | Wallet app | Yes, if tested; this is the core use |
| Reading your marketing email | Mail app, then browser | No; give a DNS link, mention the name as text |
| Scanning a code on packaging | Camera, then browser | Not alone; the code should carry a DNS address |
| Support chat about a payment | Chat app, then wallet | Yes, as text to copy, with wording about where it works |
| Following a social post | Social app’s built-in browser | No; that browser is an ordinary one |
The pattern is consistent. Where the customer is already inside a wallet, or one copy and paste away from it, the name shortens the journey. Where the customer is in a browser, a mail app or a social app, the name does nothing by itself and a DNS address has to carry them. The two are not rivals. A page on your DNS domain that shows the name, says which apps resolve it and offers a copy button is the bridge between the screen the customer is on and the screen where the name works.
If payments are the use you have in mind, the overview of payments to a name explains what the name replaces in that flow. If a website is the use, read the page on websites published on an onchain TLD with the phone limit above firmly in view.
Testing on real devices before you publish a name
A test on a phone answers a narrow question: with this name, on this device, in this version of this app, does the thing I am about to tell customers happen? It has to be asked on hardware, because simulators and desktop previews do not reproduce the keyboard, the app store version, the operating system’s handling of links or the camera.
Borrow devices that resemble your customers’, not your team’s: your customers include people who are two operating system versions behind and who have not opened their wallet app in months.
- Fix the exact claimWrite the sentence you intend to publish, for example that customers can pay to pay.yourbrand from a named wallet app. The test checks that sentence and nothing wider.
- Set the records firstConfirm that the name carries an address for every network you will accept, and note each address from the public registry record so you have something to compare against.
- Assemble the devicesTake at least one phone per operating system you serve, with the wallet apps freshly installed from the official store, and one phone whose apps have not been updated for a while.
- Enter the name three waysType it by hand, paste it from a message, and scan it from a printed code. Record what the app does each time, including what the keyboard changed.
- Compare the resolved addressCheck the address the app displays against the one in the registry record, character by character, for each network.
- Send a small real amountComplete one transfer of a trivial amount per network and confirm it arrives. A resolved address on a screen is not yet a received payment.
- Try the places it should failType the name in the phone's ordinary browser, tap it in a mail app and in a chat app. Photograph the result so that support staff know what customers will describe.
- Write down versions and datesKeep the device model, operating system version, app version and the day of the test with each result. A result without a version cannot be repeated.
Step seven is the one teams skip, and it is the most useful for the people who answer customers. Knowing in advance that the browser shows search results, that the mail app leaves the name untappable and that a given camera app shows plain text lets you write the help article before the first ticket arrives.
Keep the people who run the test separate from the person who set the records. A second pair of eyes comparing the resolved address with the registry record catches the error that matters most, which is a name that resolves perfectly to the wrong place. Since the registry record can be read by anyone on a block explorer, the comparison needs no special access.
Reading the results: what counts as a pass
A test of this kind does not return a single yes or no. It returns a grid, and the temptation is to round the grid up. Resist it. The mention you publish can only be as wide as the narrowest cell that passed.
Sort each result into one of three groups. The first is clean: the name was accepted however it was entered, the address matched, and the small transfer arrived. The second is conditional: it worked, but only after an app update, only when pasted, or only on one network. The third is a failure, including the silent kind where the app accepts the text and then offers nothing.
Clean results can be named in public. Conditional results can be named with their condition, if the condition can be said in a few words that a customer will read. Failures are left out, and so is everything you did not test. A wallet you believe supports the name but did not hold in your hand belongs in the untested group, however confident the documentation sounds.
Finally, decide what you will do with a mixed grid. A name that passes cleanly in one wallet app and fails elsewhere can still be published, with a mention that names that one app. A name that passes nowhere on a phone is not ready for an audience that lives on phones, and the honest decision is to hold it back from customer material and keep it for the desktop and wallet-native uses where it does work.
Wording the public mention for a small screen
The mention is the sentence that sits next to the name wherever you print it. On a phone it has perhaps a dozen words before the customer stops reading, and it has three jobs: say what the name is for, say where it works, and give a route that works everywhere.
The following pairs show the difference between a mention that will stay true and one that will generate tickets.
| Situation | Wording that holds | Wording to avoid |
|---|---|---|
| Checkout screen | “Paying from a supporting wallet? Send to pay.yourbrand.” | “Pay us at pay.yourbrand.” |
| Help page | “Resolves in the wallet apps named below. Support varies by app and version.” | “Works in all wallets.” |
| Printed card | Code carries a DNS address; the name is printed as text beside it | Code carries the name alone |
| Support reply | “Enter it in your wallet’s recipient field, not in your browser.” | “Just go to pay.yourbrand.” |
A few rules sit behind those examples.
Never write a sentence that implies the name opens in a browser, and avoid verbs such as “visit” or “go to”, which every phone user reads as an instruction to use the browser.
Present the name as text to copy, with a copy button where the surface allows one. Do not style it as a link unless tapping it leads somewhere that works, which in practice means a DNS page of yours that explains the name.
Make the fallback usable. For a payment, that means the full address in a form the customer can copy and compare. The customer whose wallet does not support the name should lose a few seconds, not the transaction.
Tell customers where the authoritative statement of your name lives. A line such as “our payment name is published on our website” gives them a way to check a name they received in a message against a source they already trust. That habit is worth more to them than any reassurance about the technology.
Where the DNS simply serves a phone user better
It is worth being direct about the comparison, because a product lead will be asked for it. For anything a customer reaches through a browser, the DNS is better on a phone, and not by a small margin. A DNS address is recognized by the keyboard, made tappable by every messaging app, opened by every camera and loaded by every browser, on every device, without the customer installing anything. An onchain name offers none of that.
What the onchain name offers is specific. Inside a wallet, it replaces an address that no human can read or verify by eye with a word the customer recognizes. For a holder of a TLD, the names beneath it are issued by that holder alone, which gives a brand a namespace of payment and identity names under its own control. Those are real advantages, and they sit entirely on the wallet side of the phone.
So the sensible design uses each system for what it does. The DNS domain remains the front door: the website, the links in email, the codes on packaging. The onchain name is the label customers use once they are in a wallet. A launch plan that asks the onchain name to do the DNS domain’s work on a phone will disappoint; one that confines it to the wallet will usually do what was promised.
Keeping the mention true after launch
Support for a name in a wallet app is a property of someone else’s software. It can arrive in an update and it can change in one. The mention you published on the day of your test describes that day.
Give the retest an owner and a trigger. A reasonable set of triggers is a major release of a phone operating system, a major release of any wallet app you name in public, any change to the records on the name, and any cluster of support tickets describing the same failure. The retest is the same procedure as the first test, run against the sentence that is in public.
Keep one place where the mention is defined, and have every surface draw from it: the checkout screen, the help page, the support macros, the printed material that is next due for reprint. When a retest narrows or widens what you can say, one edit should reach all of them. Printed material is the slow one, which is another reason for printed codes to carry a DNS address whose destination you can change, and for the page behind it to carry the wording.
If the name fails a retest in an app you have named, remove the app from the mention first and investigate second. A sentence that is briefly too modest costs nothing. A sentence that sends customers into a failure costs trust in the name itself.
A first test you can run with one name and two phones
You do not need a program to begin. Take one name you control, set its records, borrow two phones that differ in operating system, and run the eight steps above on a single claim. An afternoon of this tells you more about what your customers will experience than any amount of reading, and it produces the two artifacts you need: a grid of results with versions, and a draft mention that the grid supports.
If the name sits under a TLD your organization has just acquired, fold the device test into the launch plan instead of running it as a late check. The Launch Roadmap tool builds a sequence for a newly acquired TLD, and device testing belongs before any public mention in that sequence. Definitions of the terms used here are in the glossary.
Deciding which names to issue first, and where they may appear, is part of what Hush Partners covers under post-transfer activation once a TLD has changed hands through the desk. The contact form is the only way to reach us.
Questions people ask
Can we build name resolution into our own mobile app?
In principle an app can query a naming registry’s resolver itself, the way a wallet does, and show the result. Whether that is worth doing depends on what your app is for, and it makes you responsible for keeping the integration working as the registry’s interfaces evolve. Ask your engineers to read the registry’s developer documentation before anyone puts it on a roadmap.
Does a customer need to hold cryptocurrency to see what a name resolves to?
Looking up a name is a read of public data and does not require a balance. Sending to it does. A customer with a supporting wallet app and an empty balance can usually still enter the name and see the address it returns, which is useful for checking a name before funding a payment.
What if a customer saved our address from the name and we later change the record?
A wallet resolves a name at the moment the user enters it. An address saved earlier as a contact is only an address and will not follow the change. If you plan to change a record, keep the old address under your control for as long as customers might still use it, and say in your help page that the name, not a saved address, is the reference.
