# Welcome to X1ID
URL: /docs/x1id
> Own your name on X1 — yours forever. One @handle that replaces long wallet addresses and works across X1, Solana, Ethereum, and Bitcoin. Pay once, no renewals, no expiry.
One handle — @you — that resolves to your address across X1, Solana, Ethereum, and Bitcoin. Claim it once; it's yours forever. Try the resolver, then jump into the docs.} ctaHref="/docs/x1id/api" ctaLabel="Read the Resolve API" />
X1ID is live today on [app.x1id.io](https://app.x1id.io). Handles run on **X1 testnet** while we finish preparing the mainnet launch — see [Trust & transparency](/docs/x1id/trust) for exactly what that means for you.
## What X1ID is
A wallet address is 44 unreadable characters, and one wrong character sends funds nowhere. X1ID replaces it with a name you can read and share: register `@you` once and people pay it instead of copying an address, apps show you as `@you` instead of raw base58, and a single handle resolves to the right address on whichever chain the sender is on. It's **permanent** — no renewals, no expiry — and it carries a profile you own, so a wallet can finally prove who it belongs to. Start with [Why get an X1ID](/docs/x1id/why), then [claim your handle](/docs/x1id/get-started).
**`@you` is a handle, not a domain.** X1ID (`@jack`) and X1NS (`jack.x1`) are complementary — different shapes for different jobs, and many people own both. See [how they fit together](/docs/x1id/faq#x1id-and-x1ns).
---
# Why get an X1ID
URL: /docs/x1id/why
> A handle is more than a nickname — it's a permanent, multi-chain, verifiable identity you own outright. Here's what that gives you as a holder.
# Why get an X1ID
An X1ID handle is a small thing to claim and a big thing to have. But the reason it matters most comes first:
## You own it — forever
Most names you can register somewhere are really **rented**. Miss a renewal and your name lapses, and someone else can grab it. For a name people send money to, that's dangerous: an expired handle picked up by a stranger silently redirects payments meant for you.
X1ID doesn't work that way by default. A standard registration is **paid once and owned outright** — no renewals, no expiry, no subscription, no chance of losing it because you forgot to pay or stopped using it. It changes hands only when *you* decide to transfer or sell it. That permanence is the whole point, and it's what sets X1ID apart from every naming system that expires.
X1ID also offers an optional **lease-to-own** path for whoever would rather spread the cost out: pay a fraction of the price up front, then keep paying it down — every payment builds equity toward the same, pinned permanent price, and paying it off in full converts the handle to permanent immediately. It keeps the same protection standard registration is built on: a 30-day grace period means a missed payment never means an instant, silent loss the way an ordinary domain lapse does. See [the FAQ](/docs/x1id/faq#lease-to-own) for the details.
## What else you get
## Who it's for
* **Anyone who receives crypto.** Creators, freelancers, merchants, friends splitting a bill — hand out `@you` once instead of a fresh address every time.
* **People who use more than one chain.** If you hold on Solana or Ethereum as well as X1, a single handle covers all of them.
* **Anyone tired of copy-pasting addresses.** Set `@you` as your primary name and apps show your handle instead of a string of characters.
* **People who want to be recognizable on-chain.** A handle plus a profile is how others know a wallet is really yours.
You don't have to use every feature. Many people claim a handle just to receive payments to a name they can share. The profile, verification, subnames, and marketplace are all there when you want them — and cost nothing extra to skip.
## Ready?
---
# Claim your handle
URL: /docs/x1id/get-started
> Search a name, register it, point it at your wallets, and set it as your primary — a step-by-step walkthrough on app.x1id.io.
# Claim your handle
Getting an X1ID takes a few minutes. Everything happens at [app.x1id.io](https://app.x1id.io) — you'll need a wallet and a little XNT (X1's native token) to cover the one-time registration fee.
### Open the app and connect your wallet
Go to [app.x1id.io](https://app.x1id.io) and connect the wallet you want your handle tied to. This is the wallet that will own the handle, so use one you control and intend to keep.
### Search for a name you like
Type the name you want — say `you` — into the search box. The app tells you whether `@you` is available and what it costs. Shorter names cost more (see [Fees](/docs/x1id/pricing)). If it's taken, try a variation until you find one that's free.
Handles are **letters, numbers, and simple characters only** — no emoji and no lookalike symbols from other alphabets. That's deliberate: it stops anyone from registering a name that *looks* identical to yours. More on that in [Trust & transparency](/docs/x1id/trust).
### Register it
Confirm the registration in your wallet. You pay the one-time fee once, and `@you` is yours from that moment on — no renewals, ever. The name is now registered on-chain to your wallet.
### Point it at your addresses
Open your handle and add the addresses you want it to resolve to — your X1 address, and optionally your Solana, Ethereum, and Bitcoin addresses. Now when someone sends to `@you`, their wallet looks up the right address for the chain they're on.
You can prove you control each address so others see it as **verified**. Verified addresses are the ones people can trust — see [What you can do](/docs/x1id/features#prove-its-really-you).
### Build your profile (optional)
Add an avatar, a website, your social links, and a link to your decentralized site. This is what turns `@you` from a routing label into an identity people recognize.
### Set it as your primary name
Mark `@you` as your **primary** name. This is the reverse link: apps that support X1ID will now show your wallet as `@you` instead of a raw address, everywhere you appear.
## That's it
You now have a name that works across chains, a profile behind it, and an identity apps can display. From here you might want to:
**Looking someone up?** The search on [app.x1id.io](https://app.x1id.io) works two ways: type a name to check if it's free to register, or look up a handle that already exists to see whose it is, what it points to, and whether it's for sale. It's how you find a name to claim — and how you check a handle before you trust or buy it.
---
# Get paid to your handle
URL: /docs/x1id/get-paid
> Turn @you into a way to get paid. X1ID gives every handle a QR code and a shareable payment link, so anyone can pay you by scanning or tapping — no copying a long address.
# Get paid to your handle
Once your handle points at an address, `@you` becomes something people can pay in a tap. Every handle gets a **QR code** and a **shareable payment link** — no one ever has to copy a wallet address again.
An example of an X1ID pay QR.
This QR is an **example only** — it encodes the placeholder `@yourname`, which isn't a real handle, so scanning it doesn't point at anyone or move any funds. Your handle's own page generates a QR for **your** address.
## How to get paid
### Link a payment address
Add your X1 address to your handle (see [Claim your handle](/docs/x1id/get-started)). That's the address your QR and link point at — until it's set, they wait quietly rather than sending anyone to the wrong place.
### Open your handle's payment page
Your handle page shows your QR code, your address with a one-tap copy button, and the buttons to copy or share your payment link.
### Share it any way you like
Show the QR to pay in person, or send the link online. Optionally set an **amount** first and it's carried in the link, so the payer sees exactly what to send.
Because the link and QR are tied to your **handle**, they keep working for as long as `@you` is yours. Change which address receives, and the same link and code follow — no need to reprint or re-share.
Your QR encodes your plain X1 address, so wallets can scan it today. The payment link carries `@you` (plus any amount you set) — a smart wallet re-checks the handle when it's opened, so a shared link always resolves to the current `@you` rather than a stale address.
## Great for
---
# What you can do
URL: /docs/x1id/features
> Multi-chain addresses, a primary name, a web3 profile, subnames, verification, permanent ownership, recovery, locks, gifting, and a built-in marketplace — everything an X1ID handle gives you.
# What you can do
Your handle is the starting point. Here's everything you can do with it — use as much or as little as you like.
## Receive on any chain
Point `@you` at your addresses on **X1, Solana, Ethereum, and Bitcoin**. When someone sends to `@you`, their wallet looks up the correct address for the chain they're paying from — no more copy-pasting a raw base58 string (the long run of letters and numbers a wallet address is made of, e.g. `7Np1jK…pQ4mZ`). You hand out one name; it works everywhere you hold funds.
Your home chain. `@you` resolves to your X1 address so anyone can pay you on X1 by name.
Add your Solana address and receive there too. On X1 and Solana the same wallet key works, so this usually needs no new setup.
Add your Ethereum address so people on Ethereum can send to `@you` instead of a `0x…` string.
Add your Bitcoin address and collect BTC under the same handle as everything else.
You choose which chains to add — one or all four. Add more later at any time; your handle stays the same.
## Get paid with a QR code and a link
Every handle comes with a **QR code** and a **shareable payment link**, so people can pay `@you` by scanning or tapping instead of copying an address. Show the QR in person, or drop the link in a bio, a message, or an invoice.
## Be shown as @you everywhere
Set `@you` as your **primary name** and apps that support X1ID display your wallet as `@you` instead of a long address — in transaction histories, profiles, and anywhere your wallet appears. It's the difference between being `7Np1jK…pQ4mZ` and being a name people recognize.
## Build a web3 profile
Behind your handle sits a profile you control:
## Subnames
One handle can branch into purpose-built names — **`pay.you`**, **`docs.you`**, **`shop.you`** — all under the handle you already own, at **no extra registration fee**. Each one can carry its own addresses, so you can keep your money and your projects neatly separated under a single identity.
Subnames go a second level deep, too: `pay.you` can have its own **`deep.pay.you`** sub-subname, for whoever needs to split a subname further (a payments subname handing out per-client or per-project addresses, say) without touching the parent handle.
* **They're free to create** — no registration fee beyond the handle you already own.
* **You're in control.** As the owner of `@you`, you create and remove its subnames whenever you like — and as the owner of a subname, you likewise control its own sub-subnames.
* **They live under your handle.** Subnames follow the parent — there's nothing separate to renew or manage.
* **Two levels deep.** `pay.you` is a subname; `deep.pay.you` is a sub-subname of it. That's as deep as it goes.
## Prove it's really you
Anyone can *claim* to be `@you`. Verification lets you **prove** it — two ways:
Verified records are the ones others should trust. An unverified address is shown as unverified so no one mistakes an unproven claim for a confirmed one — honesty is built in, not bolted on.
## Own it permanently
Register a handle the standard way — the default — and it's yours to keep for a single, one-time payment. There's no renewal to remember and no expiry date that could hand your name to a stranger. This is a deliberate choice: a name people send money to must never quietly change owners because a payment was missed. See [Fees](/docs/x1id/pricing) for how one-time pricing works.
**Or lease-to-own it.** At registration you can instead pay a fraction of the price up front — about a quarter, by default — and build equity toward that same permanent price over time. Pay it off in full at any point and it converts to permanent immediately, no more payments. Miss a payment and you still have a 30-day grace period before the handle becomes reclaimable — the same anti-inaction protection standard registration is built on, just with a lower bar to get started. See [the FAQ](/docs/x1id/faq#lease-to-own) for the mechanics.
## A safety net
Losing access to a wallet is the nightmare scenario in crypto. X1ID gives you two tools for it:
Set up a recovery option in advance, and if you lose access to your wallet you can take your handle back. It's your insurance policy against a lost or inaccessible key — set it up while everything is fine, so it's there when you need it.
If you think your key might be compromised, lock your handle. A lock freezes it — ownership, records, and profile — so a thief can't move it or redirect your addresses while you sort things out. Unlocking has a built-in waiting period, so an attacker can't simply lock and immediately steal.
## Gift a handle
You can **pre-pay a handle for someone else** — a great way to bring a friend onto X1 who doesn't hold any XNT yet. You cover the registration up front; they claim the name with **zero funds of their own**.
### Pick a name and pre-pay it
Choose the handle you want to give and pay its registration fee up front. The amount is set aside for that specific name.
### Send the gift
Send it to a friend to claim. You can tie the gift to a specific wallet so the handle lands there no matter who opens it.
### They claim it — free to them
Your friend claims the handle without paying or holding any XNT. It becomes theirs, fully owned, from that moment.
A gift is set aside for the name you chose, and it has an expiry. If it's never claimed, the amount you pre-paid comes back to you — you're not out anything for an unclaimed gift.
## Buy and sell handles
X1ID has a **built-in marketplace** at [app.x1id.io/marketplace](https://app.x1id.io/marketplace) — no third-party site needed. Handles change hands right inside X1ID, so a sale is as safe and final as any on-chain payment.
**List** a handle you own at a fixed price. When someone buys it, ownership transfers to them and the proceeds come to you, minus the marketplace fee.
**Buy** a listed handle outright at its asking price and it's yours immediately — the perfect way to get a name someone else already registered. Select several listings at once and buy them all in a single transaction and signature; if one has changed or sold since you selected it, that row is dropped and named before you sign, and the rest still go through.
**Make an offer** on a handle even if it isn't listed. The owner can accept whenever they like; your offer is held safely until then.
**Bid** in an auction for a sought-after name. Auctions have anti-sniping protection, so a last-second bid extends the clock and gives everyone a fair chance.
Premium and reserved names — short names, brands, and well-known words — are released through the marketplace rather than by ordinary registration. A **2% fee** applies to sales; details are on [Fees](/docs/x1id/pricing).
Prefer to trade your handle like a collectible? You can optionally turn it into an NFT, which lets you sell it on standard NFT marketplaces too. It's entirely opt-in — most holders never need it — and it's a one-way step, so only do it if you specifically want that. See the [FAQ](/docs/x1id/faq).
## Next
---
# Fees
URL: /docs/x1id/pricing
> Pay once, own forever — no renewals. How X1ID pricing works — a one-time registration priced by name length, an optional NFT fee, and a 2% marketplace fee on sales.
# Fees
X1ID is designed to be simple: **you pay once and own your handle forever.** There are no renewals, no subscriptions, and no expiry dates. Here's the full picture.
## One-time registration
Registering a handle is a **single, one-time payment** in **XNT** (X1's native token). After that, the handle is yours to keep — you never pay again to hold it.
Because there's no renewal, your handle can't lapse and can't be snatched by someone else because you missed a payment. That permanence is the whole point of a name people send money to.
### Priced by length
Shorter names cost more. Here's the current price at every length — one payment to register, plus an optional one-time fee if you ever want to mint the handle as an NFT:
| Length | Tier | Register (one-time) | Mint as NFT (optional) |
| -------------- | --------- | ------------------- | ---------------------- |
| 1 character | Legendary | 500,000 XNT | +20 XNT |
| 2 characters | Uncommon | 7,500 XNT | +15 XNT |
| 3 characters | Uncommon | 1,500 XNT | +10 XNT |
| 4 characters | Uncommon | 300 XNT | +3 XNT |
| 5 characters | Common | 75 XNT | +1 XNT |
| 6–9 characters | Common | 20 XNT | +0.75 XNT |
| 10+ characters | Common | 10 XNT | +0.5 XNT |
**These are current launch prices — an introductory discount, about half the full price.** Registration is a one-time cost, and that cost steps up over time: roughly +12.5 points of the full price each quarter, reaching the full tier price about a year after launch. Because you pay once and own the name forever, **claiming earlier locks in a lower price** — a name registered today never costs more later.
These prices are set on-chain and read live — the exact figure is always shown in the app before you confirm, so you never pay anything you haven't seen. Very short names (roughly 1–4 characters) and reserved words were set aside at launch and reach owners through the [marketplace](https://app.x1id.io/marketplace) rather than direct registration (see below).
## Premium & reserved names
Some names aren't available for ordinary registration — short names, brands, tickers, and well-known words were set aside at launch. These reach new owners through the **marketplace** (a listing or an auction) rather than by direct registration. If a premium name is what you want, look for it on [app.x1id.io/marketplace](https://app.x1id.io/marketplace).
## The 2% marketplace fee
When a handle is **sold** on the X1ID marketplace, a **2% fee** applies to the sale. If you're just registering and holding your own handle, this never touches you — it only applies when handles change hands through a sale.
## Optional: turning your handle into an NFT
Turning your handle into an NFT is **entirely optional** and carries its own **separate one-time fee** (the "Mint as NFT" column above — also priced by length, and much smaller than registration). Most holders never need this — it exists for people who specifically want to trade their handle on standard NFT marketplaces. If you never mint, you never pay it. See the [FAQ](/docs/x1id/faq) for what tokenizing does.
## At a glance
| What | Cost | When |
| ------------------------------------ | ------------------------------------------------ | ----------------------- |
| Register a handle | One-time, in XNT, priced by length (table above) | Once, when you claim it |
| Hold your handle | **Free forever** | No renewals, ever |
| Turn a handle into an NFT (optional) | Separate one-time fee (table above) | Only if you choose to |
| Sell a handle on the marketplace | 2% of the sale | Only when it sells |
Whatever you're about to pay is always shown in the app before you confirm. Nothing is charged without you approving it in your wallet first.
---
# Resolve API
URL: /docs/x1id/api
> Look up the wallet a handle belongs to. Resolution is read-only and public — no wallet, no signature, and no API key. The base URL is https://api.x1id.io.
Resolve API / Resolve a handle
Resolve a handle
Look up who owns a handle. Resolution is **read-only and public** — no wallet, no signature, and **no API key**. The base URL is `https://api.x1id.io`; there is no `/v1` prefix. The REST endpoint returns the handle's **owner**; for per-chain addresses (X1 / SOL / ETH / BTC) and richer results, use the [SDK](#sdk-multi-chain-records-and-writes) below.
**Handles, not domains.** X1ID handles (`@jack`) and X1NS domains (`jack.x1`) are complementary — this resolves handles. See [how they fit together](/docs/x1id/faq#x1id-and-x1ns).
## Parameters
The handle to resolve, with or without the leading @. Case-insensitive — x1 and @X1 resolve the same record. Given as a path segment: /resolve/x1.
## Returns
Returns the resolution object for the handle. It reports the current **owner** and whether the handle is **tokenized** — it does **not** carry an addresses map or an expiry (names are permanent, so there is nothing to expire). An unregistered handle returns `404 { "error": "handle not registered" }`.
```json title="GET https://api.x1id.io/resolve/x1"
{
"input": "x1",
"name": "x1",
"namespace": "handle",
"owner": "H8FsKYhMyCN9brknY7tL4JXRbKZEjVh7XgrVmWcX1HiA",
"tokenized": false,
"verification": "owner"
}
```
| field | meaning |
| -------------- | -------------------------------------------------------------------------------------------------------------------- |
| `input` | the raw value you passed |
| `name` | the normalized handle (no `@`) |
| `namespace` | always `handle` for this endpoint |
| `owner` | the wallet that owns the handle. For a **tokenized** handle this is informational — authority follows the NFT holder |
| `tokenized` | whether the handle has been turned into an NFT |
| `verification` | `owner` when the owner controls the registry account |
**Ownership you can audit.** Every handle is a record on the X1 registry program (`8JgnNWi24bq9uzfnT9XmkWxvaWMVgoEs9bu8QsHhLe1P`), so a resolution can be verified independently on-chain. See [Trust & transparency](/docs/x1id/trust).
## Reverse lookup
Go the other way — an address back to its `@handle`. Only the address the owner has explicitly marked as their **primary** reverse-resolves, which is what prevents impersonation. An address with no primary returns `404 { "error": "no primary set" }`.
```bash
curl https://api.x1id.io/reverse/H8FsKYhMyCN9brknY7tL4JXRbKZEjVh7XgrVmWcX1HiA
# 404 → { "error": "no primary set", "input": "H8FsKYhMyCN9…VmWcX1HiA" }
```
## Health
A liveness check for the service.
```bash
curl https://api.x1id.io/health
# → { "ok": true }
```
## SDK: multi-chain, records, and writes
The REST endpoint answers "who owns this handle". For **per-chain addresses**, **records**, and **on-chain writes**, use the [`@x1id/resolve`](https://www.npmjs.com/package/@x1id/resolve) SDK. It reads chain state directly over RPC (it never depends on this API's uptime), and its writes are unsigned instruction builders you sign and relay yourself — the SDK never holds keys. The `@handle` registry is on **X1 testnet** today (`https://rpc.testnet.x1.xyz`).
```bash
npm install @x1id/resolve
```
### Read: resolve across chains
`resolve(input, { chain })` returns a `Resolved` object. X1/SOL come from the handle's authority; ETH/BTC from its on-chain records.
```ts title="resolve.ts"
import { createResolver, WasmResolver } from '@x1id/resolve';
const wasm = await WasmResolver.fromBytes(/* module bytes */);
const x1id = createResolver({ rpcUrl: 'https://rpc.testnet.x1.xyz', wasm });
const r = await x1id.resolve('@x1', { chain: 'SOL' });
// {
// input: '@x1', name: 'x1', namespace: 'handle',
// address: 'H8FsKYhMyCN9brknY7tL4JXRbKZEjVh7XgrVmWcX1HiA',
// chain: 'SOL', verification: 'verified'
// }
// A handle with no record for the requested chain is explicit, never a wrong
// address: resolve('@x1', { chain: 'ETH' }) throws
// ResolveError { code: 'no-record-for-chain' }.
```
### Read: reverse and records
```ts
const name = await x1id.reverse(address);
// 'nike' → the address's primary @handle (no '@')
// null → no primary set
const recs = await x1id.records('@x1');
// HandleRecord[]: { account, handle, coinType, chain, value, address,
// verified, updatedAt, stale } ([] when none are set)
```
### Write: sign and relay yourself
Registration and `set_primary` run from [app.x1id.io](https://app.x1id.io) today. The SDK ships builders for the rest of the registry — each returns an unsigned `{ programId, keys, data }` you assemble, sign, and send:
```ts title="subname.ts"
import { buildCreateSubnameIx } from '@x1id/resolve';
const ix = buildCreateSubnameIx({
programId, // 8JgnNWi24bq9uzfnT9XmkWxvaWMVgoEs9bu8QsHhLe1P
payer, owner, // signers — owner is the parent handle's authority
parent, subname, // the parent and subname PDAs
label: 'team', // issues team.you
});
// add ix to a transaction, sign with payer + owner, send.
```
Also shipped, same build → sign → relay shape: gifts (`buildCreateVoucherIx` + `HandleType`), integrator rev-share (`buildAddIntegratorIx`), name locks (`buildLockHandleIx`), record delegation (`buildSetRecordDelegateIx`), and typed text records (`buildCreateTextRecordIx`). Full list in the [SDK README](https://www.npmjs.com/package/@x1id/resolve).
**Which RPC?** Point the resolver at the chain that holds the names you want. `@handle` resolution is on **X1 testnet** today; on an RPC where the registry is not deployed a handle is an honest `not-found`, never a fabricated address.
---
# Invite friends
URL: /docs/x1id/referrals
> Share your referral link from app.x1id.io. When someone registers a handle through it, you're credited on-chain as their referrer — a simple way to grow your corner of X1.
# Invite friends
X1ID is more fun when the people you deal with have handles too — you can pay them by name, recognize them across apps, and stop trading raw addresses. Referrals make it easy to bring them in, and they record who introduced whom.
## How it works
### Grab your referral link
Open the **/refer** page at [app.x1id.io/refer](https://app.x1id.io/refer). Your referral link is tied to your own handle or wallet.
### Share it
Send it to friends, post it, add it to your bio — anywhere you'd invite someone to X1.
### They claim a handle through your link
When someone registers their handle after arriving through your link, your referral is attached to that registration **on-chain**, crediting you as the person who brought them in.
## What you get
**Referrals are attribution, not a payout.** Today, referrals record *who introduced whom* — they're a tracking and recognition feature. There's no monetary reward attached, so invite people because you want them on X1 with you, not for a bounty.
Referral attribution is being rolled out across X1ID on testnet, so counts may take a little time to catch up as the system settles in. The credit itself is written on-chain with each registration.
## Next
---
# Trust & transparency
URL: /docs/x1id/trust
> Permanent ownership, anti-impersonation by design, verified records, recovery, and the on-chain program address you can audit yourself.
# Trust & transparency
X1ID handles hold identity and route payments, so trust matters. Everything below is built in, and the final section gives you the on-chain address to check it all yourself.
## Your handle is permanently yours
Once you register a handle the standard way — the default — it's yours: there's no renewal to miss and no expiry that could quietly transfer it to someone else. A name people send money to must never change owners through inaction, so ownership doesn't lapse. It only moves when **you** choose to transfer or sell it.
X1ID also offers an optional lease-to-own path (pay a fraction up front, build equity toward the same permanent price over time) for whoever would rather spread the cost out. It keeps the same anti-inaction protection at its core: a 30-day grace period after a missed payment, so a leased handle can't be silently swooped in on the moment a payment is late — see [the FAQ](/docs/x1id/faq#lease-to-own).
## Built to resist impersonation
Handles use **letters, numbers, and simple characters only** — no emoji and no lookalike letters borrowed from other alphabets.
This closes a real trap. In many systems, an attacker can register a name that *looks* identical to yours using a lookalike character from another alphabet — for example a Cyrillic "а" in place of a Latin "a" in `@alice`. To the eye they're the same; to a computer they're different names. By allowing only one, plain character set, X1ID removes that whole class of attack instead of trying to spot it after the fact.
## Verified vs. unverified records
Anyone can *type* an address into a name. X1ID lets you **prove** you control your addresses, and it shows the result honestly: a proven address appears as **verified**, and an unproven one is shown as **unverified**. Nothing unproven is ever dressed up as trusted, so people know what they're relying on before they send.
## Recovery, if you lose access
You can set up recovery in advance so that a lost or inaccessible wallet doesn't mean a lost handle. Set it up while everything is working — it's the safety net that lets you get your name back later. See [What you can do](/docs/x1id/features#a-safety-net).
## You can audit it yourself
X1ID runs as a public on-chain program. You don't have to take our word for anything — you can inspect it directly on the X1 explorer.
This program is currently deployed on **X1 testnet**. The move to X1 mainnet is a separate, deliberate step we're preparing for — until then, treat handles as running on testnet. We'll make the mainnet launch clear when it happens.
## For developers
If you're building an app and want to resolve `@handles` to addresses, there's a public package, **`@x1id/resolve`**, on npm. Start at [app.x1id.io](https://app.x1id.io).
---
# Common questions
URL: /docs/x1id/faq
> Everything a holder asks — the basics, ownership and permanence, claiming a handle, using it day to day, safety and trust, the marketplace, and how X1ID fits alongside X1NS.
# Common questions
## The basics
X1ID is a naming system on X1 that gives you a single, human-readable handle — `@you` — in place of long wallet addresses. That one name can point to your addresses on several chains, carry a profile, and act as your identity across apps. You own it permanently.
A handle is your `@name` — flat and simple, like `@jack`. It's the thing people send to, the name apps show for your wallet, and the identity your profile hangs off of.
A wallet address is a long string like `7Np1jK…pQ4mZ` — unreadable, hard to remember, and unforgiving if a single character is wrong. `@you` is a name a person can actually read and share. Behind the scenes it resolves to your real addresses, so senders get the right destination without ever handling the raw string.
A single handle can point to your addresses on **X1, Solana, Ethereum, and Bitcoin**. Someone paying you is routed to the correct address for the chain they're on. You choose which chains to add.
X1ID is live now on **X1 testnet**. The move to X1 mainnet is a separate, deliberate step we're preparing for, and we'll make it clear when it happens. See [Trust & transparency](/docs/x1id/trust).
## Ownership & permanence
For a standard registration, yes. You pay once, and the handle is yours to keep — no renewals, no subscription, no expiry date. This is a deliberate design choice: a name people send money to must never quietly change owners because a payment was missed. Standard registration stays the default; see the next question for the one alternative.
Not on a standard registration — a single one-time fee and nothing after that. If you instead choose **lease-to-own** at registration (a cheaper way to start), you do pay periodically until it's paid off — see [Lease-to-own](#lease-to-own) below.
Not on a standard registration — there's no lapse for anyone to swoop in on; your handle changes hands only if you choose to transfer or sell it. A leased handle is different: miss a payment past its 30-day grace period and it becomes reclaimable — see [Lease-to-own](#lease-to-own).
No. Your handle is owned by your wallet, on-chain. We don't hold it and can't move it. It's genuinely yours.
Yes. You can transfer it to another wallet, or sell it on the built-in marketplace. See the marketplace questions below.
## Lease-to-own
A cheaper way to start: instead of paying a handle's full permanent price up front, you pay a fraction of it — about a quarter, by default — as your first year's payment. Every payment you make builds equity toward that same permanent price, pinned at the price on the day you registered. Keep paying and it's the same handle, held the same way; pay off the rest at any point and it converts to permanent immediately, with no more payments ever. There are no refunds.
You get a 30-day grace period after your paid-through date before the handle becomes reclaimable by someone else. Anyone can pay to renew a leased handle during that window — including someone other than the current holder, the same way most name registrars let a third party keep a name from lapsing.
No. Standard, one-time permanent registration is still the default and the one most people should reach for — see "Is my handle really permanent?" above. Lease-to-own is an option you choose at registration time, for whoever would rather spread the cost out.
## Getting one
Go to [app.x1id.io](https://app.x1id.io), connect your wallet, search for a name, and register it. The full walkthrough is on [Claim your handle](/docs/x1id/get-started).
A single, one-time fee in XNT, priced by how short the name is — shorter names cost more. There's no charge to keep holding it. The app shows the exact price before you confirm, and the live pricing curve is at [x1id.io/pricing](https://x1id.io/pricing). Full details on [Fees](/docs/x1id/pricing).
Yes — registration is paid in XNT, X1's native token, so you'll need a little in your wallet to cover the one-time fee.
Most everyday names are open to register directly. Short names, brands, tickers, and well-known words were set aside at launch and reach new owners through the **marketplace** — a listing or an auction — rather than by direct registration.
Short names are the rarest and most premium. They're generally released through the marketplace rather than direct registration, and they cost the most. If you want one, look for it on [app.x1id.io/marketplace](https://app.x1id.io/marketplace).
## Using your handle
They enter `@you` where they'd normally paste an address. Their wallet looks up the right address for the chain they're sending on and routes the payment there. You just share your handle.
Your handle can resolve on X1, Solana, Ethereum, and Bitcoin, and any wallet or app that supports X1ID can use it. Support is growing across the ecosystem.
Setting a handle as your **primary** creates the reverse link from your wallet back to your handle. After that, apps that support X1ID show your wallet as `@you` instead of a long address wherever you appear.
A subname is a purpose-built name under the handle you already own — `pay.you`, `docs.you`, `shop.you`. There's no extra registration; they live under your handle and are yours to create or remove anytime. See [What you can do](/docs/x1id/features#subnames).
Yes. Behind your handle is a profile you control: an avatar, your website, your social links, and a link to your decentralized site. It's what turns `@you` from a routing label into an identity people recognize.
Yes — you can attach a link to your decentralized website to your handle, so `@you` carries your site along with everything else.
Every handle comes with a **QR code** and a **shareable payment link**. Show the QR to be paid in person, or send the link online — either way people pay `@you` without copying an address. Set an optional amount and it rides along in the link. See [Get paid to your handle](/docs/x1id/get-paid).
Use the search on [app.x1id.io](https://app.x1id.io). Type a name to see if it's free to register, or look up an existing handle to see whose it is, what addresses it points to, and whether it's listed for sale — worth doing before you trust or buy one.
Yes. You can **pre-pay a handle** for someone — you cover the registration up front and they claim the name with zero funds of their own, which is ideal for onboarding a friend who has no XNT yet. A gift is set aside for the name you chose and has an expiry; if it's never claimed, your payment comes back to you. See [What you can do](/docs/x1id/features#gift-a-handle).
Referrals are **attribution, not a payout**. When someone registers through your link from [app.x1id.io/refer](https://app.x1id.io/refer), you're credited on-chain as their referrer and your referrals are tracked — but there's no monetary reward attached today. Invite people because you want them on X1 with you. See [Invite friends](/docs/x1id/referrals).
## Safety & trust
X1ID allows only plain letters, numbers, and simple characters — no emoji and no lookalike letters from other alphabets. That blocks the common trick of registering a name that *looks* identical to yours (for example, a Cyrillic "а" swapped into `@alice`). See [Trust & transparency](/docs/x1id/trust).
Set up **recovery** ahead of time and you can get your handle back even if you lose access to the wallet that owns it. Set it up while everything is working — it's your safety net for later. See [What you can do](/docs/x1id/features#a-safety-net).
**Lock** it. A lock instantly freezes your handle so it can't be moved or have its addresses redirected while you sort things out. Unlocking has a built-in waiting period, so an attacker can't lock it and immediately steal it.
Addresses can be **verified**. When someone proves they control an address, it shows as verified; an unproven one is shown as unverified. Nothing unproven is dressed up as trusted, so you know what you're relying on before you send.
Yes. X1ID runs as a public on-chain program you can inspect on the X1 explorer at `8JgnNWi24bq9uzfnT9XmkWxvaWMVgoEs9bu8QsHhLe1P` (currently on X1 testnet). See [Trust & transparency](/docs/x1id/trust).
No — it's optional and most people never do. Tokenizing lets you trade a handle on standard NFT marketplaces, but it carries a separate one-time fee and is a **one-way step**: once tokenized, the NFT holder is the owner and some tools like recovery no longer apply. Only do it if you specifically want that.
Yes — this is an optional, advanced feature. You can let a trusted person or service update your handle's records (for example, keep your addresses current) **without handing over ownership**. You stay the owner, and you can remove their access at any time.
## Marketplace
Use the built-in marketplace at [app.x1id.io/marketplace](https://app.x1id.io/marketplace). You can list a handle you own at a fixed price, accept offers, or run an auction — and buy handles others are selling.
A **2%** fee applies when a handle sells. If you're just registering and holding your own handle, this never touches you — it only applies to sales.
## X1ID and X1NS
**X1ID and X1NS are complementary, not competitors.** X1ID gives you `@`-style handles; X1NS gives you `.x1` domains. Many people own both.
They're different *shapes* of name for different jobs. **X1ID** is the handle-shaped namespace — `@jack`, flat and human, built as a payment and identity handle. **X1NS** is the domain-shaped namespace — `jack.x1` (and `.xnt`, `.xen`), hierarchical and able to have subdomains. Think of it like a social handle versus a domain name: `@jack` is to `jack.x1` what your `@handle` on a social app is to a website domain.
Not necessarily — but they complement each other, and many people will want both. X1ID covers the flat, memorable, cross-chain "pay me at `@you`" use case; X1NS covers domain-style, hierarchical naming. Owning one doesn't stop you owning the other.
Not automatically — they're separate names and can have **different owners**. That's why well-behaved wallets never silently pick between them: they always show you which namespace matched — the `@` handle or the `.x1` domain — before you send. Treat it as a feature: you always know exactly which name you're paying.
No. X1ID supplements X1NS by owning the flat, cross-chain-receive handle use case; X1NS keeps owning domain-style hierarchical naming. They work side by side.
---
# Contracts
URL: /docs/x1id/contracts
> The X1ID registry program on X1 testnet — its deployed address, the RPC endpoint it runs behind, and how to verify it yourself.
# Contracts
Testnet
X1ID runs as a single on-chain registry program on **X1 testnet**. There is no separate "resolver" or "registrar" contract split — one program owns handle registration, records, and the delegate/authority rules the [SDK](/docs/x1id/api#sdk-multi-chain-records-and-writes) and [MCP server](/docs/x1id/mcp) both read and write through.
## Deployed
| | |
| ---------- | --------------------------------------------------------------------- |
| Program | X1ID registry |
| Program ID | 8JgnNWi24bq9uzfnT9XmkWxvaWMVgoEs9bu8QsHhLe1P |
| Network | X1 testnet |
| RPC | [https://rpc.testnet.x1.xyz](https://rpc.testnet.x1.xyz) |
**Mainnet is a separate, deliberate step.** Handles registered today live on X1 testnet — see [Trust & transparency](/docs/x1id/trust) for what that means and when that changes.
This is the same address every X1ID surface is wired to: it's what `@x1id/resolve` derives PDAs against, what the [MCP server](/docs/x1id/mcp) reads via its `X1ID_PROGRAM_ID` environment variable, and what the [Resolve API](/docs/x1id/api) ultimately reads through when it answers a lookup.
## Verify it yourself
**Ownership you can audit.** Nothing here asks you to take our word for it — the program is public, and every handle it manages is a readable account on X1 testnet.
Point any Solana-compatible RPC client at the program ID above and the testnet RPC to confirm it exists and is executable:
```bash title="terminal"
solana program show 8JgnNWi24bq9uzfnT9XmkWxvaWMVgoEs9bu8QsHhLe1P \
--url https://rpc.testnet.x1.xyz
```
For the shape of individual accounts (a handle's registry entry, its text records), read through the [SDK](https://www.npmjs.com/package/@x1id/resolve) or the [MCP server's](/docs/x1id/mcp) read tools rather than parsing raw account bytes by hand — both derive the same PDAs this program expects and stay in sync with it as the source of truth.
---
# MCP server
URL: /docs/x1id/mcp
> The x1id MCP server for AI agents — every tool it exposes, the agent-verification ladder, and how to run it yourself. Not yet publicly hosted; the code is real and tested against live X1 testnet.
# MCP server
The x1id MCP server exposes `@handle` resolution and records to AI agents over [MCP](https://modelcontextprotocol.io) — Streamable HTTP transport, stateless, **no auth for read tools**, **no wallet or signer key material at all**. It's a convenience surface, not a source of truth: the two resolution tools relay [`api.x1id.io`](/docs/x1id/api) byte-for-byte, every other read goes straight to X1 through [`@x1id/resolve`](https://www.npmjs.com/package/@x1id/resolve), and the two `prepare_*` tools return an unsigned instruction for **your own wallet** to sign — this server never holds a key and never signs or broadcasts anything.
**Not yet publicly hosted.** `mcp.x1id.io` is pre-staged but not deployed — there's no public endpoint to point an agent at today. The server itself is real, complete, and smoke-tested against live X1 testnet (every read tool and both `prepare_*` builders verified against real on-chain state). Run it yourself with the steps below until the public endpoint ships.
## Tools
Eight tools on one `McpServer`, adapted from [ArcNS's own MCP server](https://mcp.arcns.io) (the EVM/ENS sibling) to x1id's real API surface:
| Tool | Reads | Notes |
| ---------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `resolve_name` | `api.x1id.io` | Byte-for-byte relay of `GET /resolve/:name`. |
| `reverse_lookup` | `api.x1id.io` | Byte-for-byte relay of `GET /reverse/:address`. |
| `check_availability` | X1 RPC | Whether the handle's PDA exists yet. |
| `get_records` | X1 RPC | A handle's live (non-stale) cross-chain address records, with per-record verification status. |
| `get_agent_manifest` | X1 RPC + the manifest URL + a live HTTP probe | Whether a handle is an AI agent, its manifest, and how far that's verified — see [Agent verification](#agent-verification) below. |
| `search_agent_handles` | an optional query API + X1 RPC | Prefix/substring search filtered to agent handles. Reports `not-available` if no query API is configured. |
| `prepare_register` | X1 RPC | Builds an **unsigned** `register` instruction. Price is computed on-chain at the landing slot — simulate before showing one. |
| `prepare_set_record` | X1 RPC | Builds an **unsigned** instruction to create or update one text record. |
Two more tools exist for x402 payments (`prepare_x402_payment`, `verify_x402_payment`) — see [Getting paid](/docs/x1id/get-paid) for the payment flow they support. Every `prepare_*` tool is read-only from this server's own perspective: it builds a transaction, but never signs or sends one.
## Agent verification
`get_agent_manifest` reports one of three levels, and only the level it actually checked — never one it assumed:
| Level | Meaning |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **L0 — declared** | Self-asserted: the handle carries an `agent.manifest` record. |
| **L1 — attested** | Backed by a live on-chain Attestation the manifest actually references. |
| **L2 — pay-to confirmed** | A live HTTP `402` probe against the agent's own payment endpoint matched a chain-verified payment address on the handle's records. |
L2 is the one thing the SDK's own agent helpers deliberately don't do — forcing a network request to an arbitrary third-party host from a library call — so it lives here, server-side, instead.
## Run it yourself
```bash title="terminal"
git clone https://forgejo.selfhsted.com/fortiblox/x1-handles
cd x1-handles/mcp
cp .env.example .env # fill in X1_RPC_URL, X1ID_PROGRAM_ID
npm install
npm run build
npm start
```
| Variable | Required | Default |
| -------------------- | -------- | ------------------------------------------------------ |
| `X1_RPC_URL` | yes | — |
| `X1ID_PROGRAM_ID` | yes | — |
| `X1ID_API_URL` | no | `https://api.x1id.io` |
| `X1ID_QUERY_API_URL` | no | unset — `search_agent_handles` reports `not-available` |
| `MCP_BIND` | no | `0.0.0.0:8696` |
See the [Contracts](/docs/x1id/contracts) page for the program ID and RPC endpoint to fill in above.