# How to write your onchain name in brand guidelines
> A chapter for your brand guidelines: spelling and casing of an onchain name, where it may appear, the note that says where it resolves, and limits for agencies.
Source: https://hush.partners/how-to-write-your-onchain-name-in-brand-guidelines
Category: Brand protection
Published by Hush Partners.
---
Brand guidelines are precise about things that look small. They fix the clear space around a logo, the one permitted shade of the house color, the way the company name is abbreviated in a legal footer. Then an organization takes control of an onchain name, a designer puts it on a poster the way a web address would be written, and nobody can say whether that was right, because the guidelines never mention it.
The gap matters more for this kind of name than for most brand elements. A logo printed slightly too small still works. A name that is typed has to be exact, character for character, and a name that resolves in some software and not in other software needs a short note beside it, or the reader will try it in the wrong place and conclude that it is broken.
This article sets out the chapter a brand and legal team can add to its guidelines: how the name is spelled and cased, how it is set in type, where it may appear, how to word the note that says where it resolves, and what agencies and partners may not do with it. It uses .yourbrand for the top-level domain and pay.yourbrand for a name issued under it.
## What a guidelines chapter on onchain names has to settle
Start with a definition, because the chapter will be read by people who have never used one. An onchain top-level domain, or TLD, is a naming suffix recorded on a blockchain as a token held in a wallet, a wallet being the software that keeps the keys controlling that token. The organization that holds .yourbrand can issue names under it, such as pay.yourbrand. Those names are looked up by wallets and by browsers with the right support, and they sit outside the domain name system that ordinary web addresses use. Two sentences of that kind, at the head of the chapter, are enough. The [glossary](/glossary) holds the fuller definitions if your readers want them.
After the definition, the chapter has five questions to answer, and each is a decision that someone in the organization must actually take before the text can be written.
The first is the canonical form: the single spelling, with its casing and its dot, that every other rule refers back to. The second is typographic treatment: how the name is set when it sits in a sentence, in a headline, on packaging. The third is placement: the surfaces where the name may be shown, and those where it may not. The fourth is the resolution note: the sentence that tells the reader which software understands the name. The fifth is permission: who may publish the name, who may ask for a new one, and what an outside agency is forbidden to do.
One boundary is worth stating in the chapter's opening lines. Brand guidelines govern how the name is shown. They do not decide who holds the wallet, who approves the issue of a name, or how a departure is handled. Those belong to an internal policy, which is a different document with a different owner. The guidelines should point to that policy in one sentence and leave it there.
## Spelling and casing of .yourbrand and pay.yourbrand
### Lowercase as the canonical form
Write the name in lowercase, always, and say so in the first rule of the chapter: .yourbrand, pay.yourbrand.
There are three reasons, and the chapter should give them, because a rule with a reason survives a creative review better than a rule without one. First, a typed name has to be exact, and a single lowercase form leaves no variant to get wrong. How the registry and the supporting software treat capital letters is a point to confirm with the registry, not one to assume. Second, a reader who copies the name will type it as shown, and a mixed-case version invites the question of whether case matters. Third, lowercase is the visual convention people already associate with addresses, which tells them at a glance that this is something to type, not a slogan.
This rule will collide with the wordmark. If the company writes its own name with a capital, or entirely in capitals, the brand team will want the onchain name to follow. Resist it. The wordmark and the onchain name are two different objects: one is a mark to be recognized, the other is a string to be entered. The guidelines can show them side by side precisely to make that point.
### The dot belongs to the name
When the TLD is mentioned alone, it carries its leading dot: .yourbrand, never "yourbrand TLD" and never "dot yourbrand" in running text. The dot is what distinguishes the suffix from the company name in a sentence where both appear.
When a name under the TLD is written, the dot separates its two parts and nothing else does: pay.yourbrand. No space on either side of the dot, no hyphen in its place, no slash. The chapter should state that the name is never preceded by a web protocol prefix or by the three letters that traditionally open a web address. Either addition tells the reader to type it into an ordinary browser, which is exactly the instruction the resolution note exists to correct.
### Two levels and no more
Every name in the guidelines has two levels: the TLD and one label in front of it. Give the approved names as a closed list in the chapter itself or in an annex that the chapter cites. A list is better than a pattern, because a pattern invites people to invent names that fit it.
Explain in one sentence why the list is closed: on the registry, only the holder of a TLD can issue a name under it, so a name that is not on the approved list either does not exist or was not issued by the organization. That sentence does a great deal of work later, when an agency proposes a campaign name of its own.
### Characters to exclude
Limit approved names to the unaccented letters a to z, the digits and, if you must, the hyphen. Accented letters, characters from other scripts and symbols create names that are hard to type on some keyboards and that can be confused with other names. The subject of lookalike characters deserves its own treatment; for the guidelines, the rule is simply that no approved name contains them.
## Setting the name in type without breaking it
A name that must be typed exactly has typographic needs that a tagline does not. The chapter should cover five of them.
**Typeface.** Set the name in the house typeface where its letterforms are unambiguous. Check three pairs in particular: lowercase L against capital I and the digit one, the letter O against zero, and the letter pair r and n set close together against m. If the house face fails on a name you use, the guidelines name a second face for onchain names only, usually the one already approved for code or data.
**Emphasis.** One weight heavier than the surrounding text, or the same weight in the house accent color. Not italic, which distorts letterforms, and not underlined, which makes a printed name look like a web link and a digital one look clickable when it may not be.
**Line breaks.** The name never breaks across two lines. In digital layouts, the team that builds the page keeps the string together. In print, the layout is adjusted. A hyphen added at a line end would be read as part of the name.
**Sentence punctuation.** Avoid ending a sentence with the name, because the full stop that follows will be read, and copied, as part of it. Rewrite the sentence so the name sits in the middle, or set the name on its own line. The same applies to a comma or a closing parenthesis directly after the name.
**Trademark symbols.** These are a question for counsel, not for design. Whether a registered or unregistered mark symbol may accompany the string depends on what is registered, in which classes and in which country, and the rules vary. Whatever the answer, the symbol is never placed where it could be read as part of the name to type. Many teams keep the symbol on the wordmark and leave the onchain name bare.
## Where the name may appear, surface by surface
Placement is where guidelines usually go vague, and where a table earns its place. The governing idea is simple: the name may appear wherever the reader can act on it with software that resolves it, or wherever the resolution note fits beside it. It should not appear where it would be mistaken for a web address and the note cannot follow.
| Surface | May it appear | Condition |
| --- | --- | --- |
| Checkout and invoices | Yes | Payment name only, long note |
| Help center and product pages | Yes | Long note, with test instructions |
| Social profile and posts | Yes | Short note in the same post |
| Press releases | Yes | Long note in the boilerplate |
| Packaging and print | With approval | Short note printed beside it |
| Outdoor and broadcast | Rarely | Only where the note is legible |
| Business cards and email footers | Approved names only | Short note |
| Contracts and legal notices | With counsel | Never as sole identifier |
Some of these rows need a sentence of reasoning in the chapter.
On a checkout page or an invoice, the name is a payment instruction. That raises the standard: the name shown must be the approved payment name and nothing else, the long form of the note must be present, and finance must have signed off on the page. Guidance on how [payments to a name](/onchain-tld-payments) work belongs in the finance team's procedures; the guidelines only fix how the name is displayed.
On packaging and in outdoor advertising, the difficulty is permanence and space. A printed pack lives for months, and coverage of the name across software changes over that time. A note that was accurate when the artwork was approved may undersell or oversell the name later. That is why print needs approval case by case, and why the short note is worded so that it stays true as coverage grows.
In contracts, the name is never the only way a party or a payment destination is identified. It may be cited alongside the legal entity and the usual details, if counsel agrees. Whether a name has any legal effect as an identifier depends on the contract and the country, and your own counsel decides.
Where a website is published on the name, the same placement rules apply to the address of that site, with the note explaining which browsers reach it. The practical limits are set out on the page about [websites on an onchain TLD](/onchain-tld-websites).
## The mention that says where the name resolves
This is the rule that makes the chapter worth writing. An onchain name is not part of the ICANN DNS root, so a browser with no added support will not open it, and a wallet that has not integrated the registry will not recognize it. A reader who meets pay.yourbrand with no explanation will, quite reasonably, try it in a search bar.
The facts the note rests on are narrow and should be stated narrowly. For names on the Freename registry, support exists in Bitcoin.com Wallet, in MetaMask by way of Freename's resolver, and in desktop browsers that have the Freename Web3 extension installed. That is partial coverage, and it moves: software is added, and integrations change. The page on [names that resolve in wallets](/onchain-tld-wallets) describes the wallet side, and the register of [what works at present](/whats-live) is the reference to check before any wording is approved.
From those facts follow four requirements for the note.
It names the kind of software, not a promise. "In wallets and browsers that support it" is true and will stay true. A sentence implying that the name works everywhere is false and will be read as a claim by the organization.
It travels with the name. The note appears on the same surface as the name, in the same language, at a size a reader can read. A note on another page does not count.
It never suggests a fallback that defeats it. Do not write "or search for our name", which sends the reader to results the organization does not control. Offer the organization's ordinary web address as the alternative.
It is approved text. Writers choose between approved variants; they do not draft their own.
There is an honest limit to record in the chapter as well. For reaching a general audience with a single address that opens in any browser on any device, the DNS is simply better, and the guidelines should say that the organization's web domain remains the primary address in all mass communication. The onchain name is shown where it does something the web address does not: receiving a payment in a wallet, identifying the organization inside software that reads the name.
## Approved wordings for the resolution note
Give writers three lengths and tell them which surface takes which. The wordings below are models to adapt; legal should approve the final text, and consumer protection and advertising rules vary by country.
| Variant | Model wording | Use |
| --- | --- | --- |
| Long | pay.yourbrand is an onchain name. It works in wallets and browsers that support it. Coverage varies. See our help page. | Web, invoices, press |
| Short | Onchain name. Works in supporting wallets. | Print, social, footers |
| Spoken | Our onchain name, pay dot yourbrand, for wallets that support it. | Audio, events, video |
A few drafting points sit behind these models.
Whether to name specific software is a real choice. Naming a wallet is more helpful to the reader and is accurate as far as the registry's stated support goes. It also uses another company's name in your material, which raises its own questions of permission and of keeping the text current when support changes. A workable rule is that named software appears only on pages the organization can edit within a day, such as the help center, and never in print. In print, the note stays generic and points to the help page by its ordinary web address.
The help page is part of the note. It says which software the name has been tested in, by whom and how, and it is the one place that is updated when coverage changes. Every other surface refers to it. That design means a change in coverage requires one edit, not a reprint.
Do not attach adjectives. Words such as "secure", "verified" or "official" beside the name promise something the name alone does not deliver. A name tells the reader where it points; it does not vouch for the software in between or for the transaction. If the organization wants to tell customers which names are its own, it publishes the closed list on its website and says that anything else is not issued by it.
## What agencies and partners may not do with the name
Most misuse of a brand's onchain name by its own suppliers is well meant. An agency wants a campaign name, a distributor wants to look connected, a developer needs something to test with. The guidelines prevent this by being explicit, and the agency contract makes the guidelines binding. Whether a given restriction is enforceable depends on the contract and the governing law, which is for counsel.
The chapter should state the following prohibitions in plain terms.
**No registration on the organization's behalf.** An agency, partner or contractor does not register any name that contains the brand, in any naming system, on any TLD, whether to use it or to keep it for the client. A name held in a supplier's wallet is controlled by the supplier, whatever the invoice says. If a name is wanted, the request goes to the internal owner named in the chapter.
**No invented names under .yourbrand.** A name appears in creative work only if it is on the approved list. Mock-ups that show a name not yet issued are marked as mock-ups and never leave the review room. Since only the holder can issue names under the TLD, a published name that was never issued points nowhere, and customers will be told it is the brand's.
**No alteration.** No capital letters, no added prefix, no abbreviation, no substitution of a similar-looking character for visual effect, no splitting of the name across design elements so that the dot disappears.
**No claims.** No statement that the name works in all wallets or browsers, no adjectives of assurance, no removal of the resolution note to save space.
**No pairing with third-party marks.** The logo of a wallet, a registry or a blockchain does not appear beside the name unless that party's own guidelines allow it and the organization's counsel has approved the use.
**No records.** Agencies do not ask for, and are not given, the means to set or change what the name points to. On the registry, only the holder manages a TLD, and the guidelines should say that this is not delegated.
Put a positive rule beside the list so that suppliers know what they can do: use approved names from the list, in the approved form, with an approved note, on the surfaces the table allows, and ask the named owner for anything else. A supplier who sees a name that imitates the brand reports it to the same owner and does nothing further; monitoring is a separate function, described under [namespace watch](/namespace-watch).
## The do and do not page
Guidelines are consulted in a hurry. One page, placed at the front of the chapter, should let a designer or a copywriter get the name right without reading anything else.
| Subject | Do | Do not |
| --- | --- | --- |
| Casing | pay.yourbrand | Pay.YourBrand or PAY.YOURBRAND |
| TLD alone | .yourbrand, with its dot | yourbrand, dot yourbrand |
| Prefixes | The bare name | A web protocol or www before it |
| Line ends | Keep the name whole | Break or hyphenate it |
| Sentence | Name in mid-sentence | Full stop directly after it |
| Emphasis | Heavier weight or accent color | Italic or underline |
| Note | Approved variant beside the name | Name alone, or "works everywhere" |
| New names | Ask the named owner | Invent or register one |
## Keeping the chapter accurate as coverage changes
A chapter on logo usage can go untouched for years. This one cannot, because one of its rules describes the outside world.
Name an owner for the chapter, by function. In most organizations that is the brand lead, with a named reviewer in legal and a named contact in the team that holds the wallet. The owner keeps the approved list of names, approves requests to show a name on a new surface, and signs off any change to the wording of the note.
Set two triggers for review. One is a calendar interval that the organization chooses and writes down. The other is an event: a change in the software that resolves the name, a new name issued under the TLD, a new market, or a customer complaint that the name did not work. The second trigger matters more than the first.
## Drafting the chapter: a first working session
The chapter can be drafted in one working session if the right people are in the room and the decisions above are taken in order.
From blank page to approved chapter
Fix the list of namesWrite down every name the organization has issued under .yourbrand and intends to show publicly. Anything not on the list is out of scope until it is added.
Test before you writeHave someone outside the project try each name in the software the registry says it supports, on real devices, and record what happened. The note is drafted from that record.
Decide the canonical formLowercase, dot, two levels, permitted characters. Check the house typeface against each name and choose the fallback face if needed.
Fill in the surface tableGo row by row with brand, legal and finance, and write the condition for each surface the organization actually uses.
Approve the three notesLegal signs off the long, short and spoken wording in every language in use, and the help page they point to is published first.
Write the supplier rulesList the prohibitions, add the positive rule, and ask counsel to reference the chapter in agency and partner contracts.
Name the owner and publishRecord the owner, the review triggers and the version, then replace every older copy on the brand portal.
If the first step produces an empty list, the chapter is premature and a different question comes first. A team may discover at this point that it has never checked whether the TLD matching its brand is in its hands. The free Trademark Name Check on the page about [trademark TLDs](/trademark-tlds) is a reasonable place to begin, and the overview for [brands and legal teams](/brands-and-legal-teams) sets out the options that follow.
That earlier step is where Hush Partners works. When the TLD the chapter would describe has still to be acquired, an organization can mandate the desk to find and approach its holder. The desk is reached through the [contact form](/contact).
## Questions people ask
### Should the onchain name replace the web address in the logo lockup?
No. A lockup that pairs the wordmark with an address is seen by everyone, on every device, and the web address is the one that opens for all of them. Keep the web address in the lockup and give the onchain name its own approved placement with its note.
### Can a campaign use a hashtag that looks like the name?
A hashtag cannot contain a dot, so it would be a different string and would teach the audience the wrong spelling. If a campaign needs a tag, choose one that is clearly a tag and show the name separately in its canonical form.
### What do we do with old material that shows the name without a note?
Treat it as you would a superseded logo. Correct digital material at the next edit, withdraw files from the brand portal, and let printed stock run out unless the name shown is one that is no longer approved, in which case counsel decides whether it should be recalled.