# Launch your TLD
URL: /docs/x1id/launch-your-tld

> Create your own X1NS top-level domain (like .pepe) permissionlessly on the X1ID registry. Pay a one-time creation fee, become the TLD creator, and earn 75% of every name registered under it — enforced on-chain. The Namespace account, the payout controls, and an honest account of what's live.

# Launch your TLD

<Pill tone="mainnet">Mainnet</Pill>

<LlmActions />

Anyone can create their own **X1NS top-level domain** — a `.yourbrand` — directly on the X1ID registry program. Pay a one-time creation fee, and you become the TLD's **creator**: every name registered under it (`alice.yourbrand`) routes **75% of the price to you** and 25% to the X1ID treasury, enforced on-chain. Names under your TLD are first-class handle accounts — they resolve, they index, they appear in the marketplace.

These are **on-chain instructions** on the registry program (`8JgnNWi24bq9uzfnT9XmkWxvaWMVgoEs9bu8QsHhLe1P`), built into X1ID's own program — not a fork of SNS, ENS, or anyone else. You call them the same way you call [registration](/docs/x1id/register): assemble the instruction, sign, and send.

<Callout type="info">
  **What's enforced on-chain today.** The 75/25 split is enforced on **every primary registration** under a TLD, and a permissionless [referrer cut](#referrers-earn-a-cut) composes on top of it. On **resale** through the X1ID marketplace, the creator also earns a fixed share of the royalty: see [Resale royalty](#resale-royalty).
</Callout>

<Callout type="warn">
  **Registrations and marketplace actions may be paused.** The registry has an emergency lockdown, used for example during a security audit. While it's on, the program rejects new registrations, NFT mints, reserved-name and gift claims, TLD creation, and new listings, offers and auctions (`ProtocolLockedDown` / `MarketPaused`). Resolution, transfers, `set_primary` and records keep working, as do exits such as cancelling a listing, completing an existing sale, and lease renewal. Check the banner on [app.x1id.io](https://app.x1id.io), or read the flag from the `Config` account with the SDK's `readPauseState`. For a TLD, that means `create_namespace`, `register_under_namespace` and `register_under_namespace_v2` are rejected while the lockdown is on. Setting your TLD's prices (`set_namespace_pricing`) is not blocked by the lockdown, because it moves no value.
</Callout>

## Create a TLD

`create_namespace(label)` is **permissionless** — no admin approval. It:

1. Charges the one-time **creation fee**, currently **1,000 XNT** (admin-configurable; read `Config.namespace_creation_fee_lamports`), from the payer to the treasury.
2. Refuses any label on the [**reserved denylist**](#reserved-tlds) — the ecosystem roots and a seeded set of brand/trademark labels are protected.
3. Initializes the `["namespace", label]` account, records **you** (the payer) as the `creator`, sets your `creator_payout` wallet, sets the creator share to the default **75%** (7500 bps) with that same value frozen as the floor, and sets the registration mode to [**Open**](#open-vs-invite-only) (anyone may register under it).

A label is canonical ASCII (`a-z`, `0-9`, `-`), 1–16 characters.

<Callout type="info">
  The creation fee is currently **1,000 XNT** (admin-configurable; read `Config.namespace_creation_fee_lamports`). It's a tunable config value rather than a hardcoded number, so read it from the on-chain `Config` account (or check the app) right before you create. Creating a TLD does **not** register any names under it; that's a separate step per name.
</Callout>

## The Namespace account

Each TLD is one on-chain `["namespace", label]` account:

| Field                      | Meaning                                                                                                                                                   |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label`                    | the TLD, e.g. `pepe`.                                                                                                                                     |
| `status`                   | `Active`, `Paused`, or `Retired`. New names can be registered only while `Active`; existing `name.tld` handles keep resolving regardless.                 |
| `created_at`               | creation timestamp.                                                                                                                                       |
| `creator`                  | the wallet that created the TLD. The only key that can rotate the payout, set the [price table](#set-your-own-prices), or raise the share. Never changes. |
| `creator_payout`           | the lamport destination for the creator's share of every registration.                                                                                    |
| `creator_share_bps`        | the creator's cut in basis points (default `7500` = 75%).                                                                                                 |
| `creation_share_floor_bps` | the floor the share can never drop below — the split frozen in at creation, protecting everyone who registered under the advertised terms.                |
| `registration_mode`        | `Open` (the default — anyone may register) or `InviteOnly` (only the creator may). Flipped anytime by the creator. See [below](#open-vs-invite-only).     |

## Register a name under a TLD

Two instructions create `name.tld` as a first-class handle at the PDA `["handle", label, name]` (ordinary `["handle", name]` handles are untouched):

* **`register_under_namespace_v2(name, handle_type, max_price_lamports)`** works on every TLD. If the creator has [set prices](#set-your-own-prices), it charges the creator's price for the name's length; otherwise it charges the **global tier table** price, the same length-based pricing as a bare handle. It refuses to charge more than `max_price_lamports`, so pass the price you quoted to the buyer.
* **`register_under_namespace(name, handle_type)`** is the original instruction. It still works, unchanged, on a TLD that has never set prices, and charges the global tier table price. On a TLD whose creator has set prices it fails with `NamespacePricingRequiresV2`, so nobody can buy at the global price by using it.

Whichever instruction you use, the price is split:

* **`creator_share_bps`** (75% by default) → the TLD's `creator_payout`.
* The **exact remainder** → the treasury.

The split is value-conserving: `creator_cut + treasury_cut == price`, floor-rounded on the creator side with treasury taking the remainder, so no lamport is created or lost.

## Set your own prices

By default, a name under your TLD costs the same as a bare handle of the same length, from the global tier table. As the creator you can replace that with your own price table using **`set_namespace_pricing(label, tier_lamports)`**.

* **Who can call it.** Only the TLD's `creator` wallet signs. X1ID's admin and the treasury can't set or change your prices; it's the same trust model as your payout and registration-mode settings.
* **What you set.** `tier_lamports` is ten prices in lamports, one per name length: entries 0 through 8 price 1- to 9-character names, and entry 9 prices every name of 10 or more characters. You always send all ten. The prices don't have to go up or down with length, so a premium TLD can charge more for short names and a community TLD can price everything the same.
* **Floor and ceiling.** Every entry must be at least **1 XNT** (`NAMESPACE_TIER_FLOOR_LAMPORTS` = 1,000,000,000 lamports) and at most **100,000,000 XNT** (`NAMESPACE_TIER_MAX_LAMPORTS`). An entry below the floor fails the whole call with `NamespaceTierBelowFloor`, and one above the ceiling fails with `NamespaceTierAboveMax`. Both limits are constants in the program, so no admin setting can change them. The floor makes sure the treasury's share of every sale still covers the rent of the accounts each registration creates (about 0.026 XNT), even with your share at the 80% cap and a referrer taking their full cut.
* **Flat prices.** Your table is used as is. Unlike the global table, there's no launch-time or volume price ramp.
* **Changing prices.** Call `set_namespace_pricing` again with a new table at any time, including while the TLD is paused. A new table affects future registrations only; names already registered are never touched.
* **Cost to you.** The first call creates the TLD's pricing account at the PDA `["ns_pricing", label]` and grows your `Namespace` account by one byte that marks the TLD as priced. You pay the rent for both.

Accounts, in order: `creator` (signer, writable), `namespace` (`["namespace", label]`, writable), `namespace_pricing` (`["ns_pricing", label]`, writable), and the system program.

<Callout type="warn">
  **Setting prices is one-way.** There is no instruction to delete a price table or return to the global tier table. You can set a table that matches whatever prices you want, but once your TLD is priced, buyers must use `register_under_namespace_v2`: the original `register_under_namespace` fails with `NamespacePricingRequiresV2` for your TLD. Make sure the apps selling your names support v2 before you set prices.
</Callout>

### Registering with v2

`register_under_namespace_v2` takes the same accounts as `register_under_namespace`, in the same order, with two differences:

* The three optional accounts after `sysvar_instructions` (the referrer's integrator account, the integrator allowlist, and the minter authorization) must always be present. Pass the registry program ID in any slot you don't use; that is how Anchor marks an optional account as absent.
* The TLD's `["ns_pricing", label]` PDA comes last, as the first remaining account (position 24). Pass it even if the creator has never set prices: an address that holds no account means "use the global tier table".

The program checks the pricing account before any XNT moves. If it isn't the canonical PDA for this TLD, isn't a valid price table, or is missing (including when it slides into an optional slot because a placeholder was left out), the call fails with `NamespacePricingMismatch`.

`max_price_lamports` protects the buyer. If the creator raises prices, or the global price ramps up, between your quote and the transaction landing, the call fails with `PriceExceedsMax` instead of charging more. The buyer loses only the network fee.

The split is the same on both instructions and on both price sources: the creator's share, any referrer's cut from the treasury's portion, and the treasury's remainder, all checked on-chain.

## Resale royalty

Names under a TLD are always tokenized, so a resale through the X1ID marketplace (`buy_handle` on a fixed-price listing) withholds the 2.5% royalty from the sale price, and for a `name.tld` that royalty is split on-chain:

* **75%** of the royalty → the TLD's `creator_payout`.
* The **exact remainder** (25%) → the treasury.

This secondary split is a fixed protocol constant (`SCOPED_ROYALTY_CREATOR_BPS = 7500`). It is independent of `creator_share_bps`, which governs primary registrations only, so raising your primary share does not change it. The buyer's transaction must include your current `creator_payout` account; the program checks it against the Namespace record, so nobody can redirect your cut. The NFT's metadata also declares the same 75/25 creator split, which marketplaces that honor Metaplex royalties read; outside the X1ID program, whether that royalty is paid depends on the marketplace.

## Open vs. invite-only

Every TLD carries a `registration_mode`, and the **creator alone** flips it — trustlessly, with no admin or treasury signature — via `set_namespace_registration_mode(mode)`:

* **`Open`** (the default, set at creation) — **permissionless**: anyone may buy `name.tld` and assign ownership to any wallet they choose, exactly like a bare `register`.
* **`InviteOnly`** — only the namespace **creator** may register names, assigning each new handle's owner to an invitee pubkey they pass in. The model for a curated or members-only community.

Fees and the 75/25 split are **identical** in both modes — invite-only changes *who* may call `register_under_namespace` or `register_under_namespace_v2`, not the price or the payout. Flipping the mode affects only future registrations; names already registered are untouched. (In `Open` mode a registration by anyone other than the creator is allowed; in `InviteOnly` mode anyone but the creator is rejected with `NamespaceInviteOnly`.)

## Referrers earn a cut

Registrations under a TLD compose with X1ID's **permissionless referrer** (integrator) rev-share. Anyone can self-register as a referrer — `register_integrator` needs no allowlist or admin approval — and then earn a share of registrations they drive, up to a hard cap of **20%** (`MAX_INTEGRATOR_RATE_BPS`).

On a namespaced (`name.tld`) sale, the referrer's cut comes **entirely out of the treasury's 25%** — the creator's 75% is never touched:

* **Creator** → `creator_share_bps` (75% by default) of the price. **Untouched by any referral.**
* **Referrer** → up to 20% **of the treasury's 25% portion** (not of the whole price).
* **Treasury** → the exact remainder.

The whole thing stays value-conserving: `creator + referrer + treasury == price`, checked on-chain. A sale with no referrer is byte-identical to the plain 75/25 split.

<Callout type="info">
  This is the same referrer system the consumer [invite flow](/docs/x1id/referrals) credits — here it's the on-chain, revenue-sharing form that composes onto TLD registrations. The 20% cap is of the treasury's portion, so a creator's advertised 75% is mathematically guaranteed regardless of who referred the buyer.
</Callout>

## Payout controls (creator-owned, trustless)

Two instructions let a creator manage their TLD's economics without anyone's permission:

<Cards>
  <Card icon="Wallet" title="update_namespace_payout(new_payout)" description="Rotate the wallet your share flows to. Signed by the creator alone — no admin or treasury signature. Affects only future registrations." />

  <Card icon="TrendingUp" title="set_namespace_creator_share(bps)" description="Raise your share, up to a hard cap of 80% (MAX_CREATOR_SHARE_BPS = 8000), so the treasury always keeps at least 20% of every primary sale. A one-way ratchet: it can go up but never below the creation floor, so names sold under the advertised split stay protected. Callable by the creator or an admin." />
</Cards>

## Reserved TLDs

Permissionless creation is gated by an on-chain **denylist** so nobody can grab a sensitive root. Each reserved label is its own `["reserved_namespace", label]` account, and `create_namespace` refuses any label for which that account **exists** — the same "shadow account" test the registry uses to stop a voucher shadowing a live handle.

The denylist is **seeded at launch** with:

* the **ecosystem roots** — `x1`, `xnt`, `xen` — and neighboring-chain roots like `sol` and `eth`, so a TLD can't impersonate core infrastructure;
* a curated block of **brand and trademark labels** (the same classes the handle registry's [reserved-names policy](/docs/x1id/register) protects), so high-value and impersonation-prone names are held rather than sold to the first buyer.

It is **admin-managed and extensible** over time — the seed set is a starting point, not a fixed ceiling:

* **`add_reserved_namespace(label)` / `remove_reserved_namespace(label)`** — add or lift a denylist entry.
* **`create_namespace_admin(label)`** — a fee-free sibling of `create_namespace` that **bypasses** the denylist, so X1ID itself can stand up the reserved core roots (`x1` / `xnt` / `xen`) as real, operational TLDs.

Try to create a reserved TLD and the call reverts with `NamespaceReserved` — check availability (in the app or by deriving the `["reserved_namespace", label]` PDA) before you build a launch around a label.

## Admin controls

Beyond the denylist, one instruction is an admin-only safety rail:

* **`set_namespace_status(status)`** — the kill switch. Flipping a squatted or abusive TLD to `Paused`/`Retired` stops new registrations under it (existing `name.tld` handles keep resolving).

Everything else about a TLD — the payout wallet, the share (upward), the [registration mode](#open-vs-invite-only), and the [price table](#set-your-own-prices) — is **creator-owned and trustless**, needing no admin involvement at all. The kill switch doesn't touch your prices either.

## How names under a TLD resolve

`alice.pepe` resolves like any X1NS name. Point the [SDK](/docs/x1id/sdk) or the [public Resolve API](/docs/x1id/api) at it, or go through the [Universal resolver](/docs/x1id/universal-resolver). As always, the response names which namespace answered — `@alice`, `alice.x1`, and `alice.pepe` are distinct identities and are never conflated.

## Next

<Cards>
  <Card href="/docs/x1id/contracts" icon="FileCode2" title="Contracts" description="The registry program these instructions live on, and how to verify it yourself." />

  <Card href="/docs/x1id/faq" icon="CircleHelp" title="X1ID & X1NS" description="How @handles and X1NS domains fit together." />

  <Card href="/docs/x1id/pricing" icon="Tag" title="Fees" description="How registration pricing works across the tier table." />
</Cards>