Skip to content

Build a branded registrar storefront

Use this guide when you want customers to search, buy and manage Handshake second-level domains (SLDs) through your own website, with Headless Domains providing the registration infrastructure. Give the build brief to your developer or AI coding agent.

Ownership, management and self-custody

For alice.tx, .tx is the top-level domain (TLD) and alice.tx is the SLD. These are different assets and permission boundaries.

Concept What it means for your integration
TLD custody Who controls the Handshake root's blockchain keys. Changing the storefront does not require changing this.
SLD holder The customer or account recorded as holding a registration, with its term and entitlement.
Management authority Which authenticated customer, organization or registrar may read or change that exact registration. Paying for a name or owning its TLD does not establish a customer login or blanket delegated access.
Branded management Your website presents the account and DNS interface; your server calls the authorized management API.
Wallet self-custody A separate asset/protocol arrangement. An API key, custom nameservers, or a branded dashboard does not turn a registry-managed SLD into a wallet-held blockchain asset.

Customers do not need wallet self-custody to use a branded SLD manager. Agree who the recorded holder is, how customers authenticate, and how they recover or move their names if the storefront closes. Do not advertise wallet custody, NFT ownership, permanent registration or unrestricted transfers unless the specific product implements them.

Choose the integration that matches the registrations

Mode Accounts and payments Starting point
Branded discovery with Headless Domains checkout The buyer signs in, pays and manages through Headless Domains. Your site performs public search and hands off. Start here for an existing .tx / .hey storefront.
Partners white-label registrar Your service authenticates customers, collects retail payment and maps customers to registrations. Approved server credentials call Partners APIs; the partner's prepaid balance funds provisioning under its agreed terms. Partners integration. Confirm seller permissions, billing and management access before changing from shared checkout.
Organization-managed portfolio An organization credential and a stable external_customer_id select an authorized customer portfolio. Namespace grants and domain bindings are required. Organization API, for namespaces and registrations supported by that contract.

A public namespace listing is not an organization or reseller grant. As verified on November 14, 2026, .tx and .hey advertise source: partners in the public capability feed. Organization registration currently requires an explicit local namespace grant; creating an organization does not import Partners marketplace purchases or legacy holder claims into its portfolio. Recheck capabilities and your authenticated permissions before implementation.

The legacy personal reseller API, organization API, Partners API and registrar-channel APIs use different authority models. Do not mix their keys, customer identifiers, order IDs or payment examples.

Stage 1: search, pricing and shared checkout

This stage can use a static website and needs no private API key.

Read the live contract

GET https://headlessdomains.com/api/v1/domains/capabilities?namespace=tx
GET https://headlessdomains.com/api/v1/domains/search?q=example.tx
GET https://headlessdomains.com/api/v1/integrations/shakeshift/pricing

Use namespace=hey and q=example.hey for .hey. Example labels are not promises of availability. The capability response contains a data array; select the exact namespace. Search returns a results array; match both the full domain and tld instead of taking the first result.

  • Normalize a label or full name and append the site's suffix once. The current ASCII label format permits 1–63 letters, digits or hyphens, with no leading or trailing hyphen. Handle IDNs only with a supported normalization flow.
  • Enable checkout only for an authoritative available result with checkout_enabled: true, no read-only restriction and no provider error.
  • Treat missing results, timeouts, malformed responses and provider failures as availability unconfirmed, never as available or definitely taken.
  • For claim_required / protected_legacy_name, show Existing registration — recovery required and link to the recovery guide. Do not offer a new purchase or infer expiry from old export data.
  • Display the search result's human retail price and currency. Multiply by the selected term only when registration_term_model is annual_price_times_years. Respect max_registration_years. The pricing feed supplies standard, non-premium annual registration and renewal prices; checkout revalidates the actual name and price. Do not hardcode a price from a screenshot or this guide.
  • Use bounded requests and a direct Headless Domains search fallback. Browser requests require CORS permission for your exact origin. If your origin is not permitted, use the redirect fallback or request integration support; do not add private credentials to browser requests.

Hand off the chosen name and term

For a Partners-backed result, use the matching capability's urls.quote template, substituting the encoded full domain and validated integer years. Preserve any provider parameter supplied by that template. Treat it as routing information, not authorization. Allow only the expected HTTPS Headless Domains origin when constructing external links.

The current shared checkout route has this shape:

https://headlessdomains.com/marketplace/pilot/checkout?domain=example.tx&years=1

Headless Domains performs buyer sign-in, quote review, payment and fulfillment. Do not simultaneously create a Partners registration or charge on your site. Payment confirmation and completed registration are separate states.

Provide these visible destinations:

  • Manage my domains: https://headlessdomains.com/dashboard
  • Recover an existing name: https://headlessdomains.com/recover
  • Support: https://headlessdomains.com/contact
  • How to open Handshake names: resolver guide

Use the authenticated response's management destination for an individual name when available. Never construct an order ID or treat a browser query parameter as proof that a purchase belongs to the visitor.

Stage 2: management on your own site

For the .tx / .hey GFAVIP login and read-only dashboard milestone, use the SSO and portfolio implementation handoff. It documents the existing code flow with state/S256 PKCE, the recovered-name option on the existing domain API, and the rollout and acceptance checklist. Check its release status before enabling Stage 2.

Keep the Stage 1 manager link working while adding your branded account area. Start with authorized inventory/status reads, then enable each supported write.

Establish the customer boundary first

  1. Confirm the actual registration path: Headless Domains marketplace purchase, activated legacy holder claim, direct Partners sale, or organization-bound domain. The suffix alone does not select a management API.
  2. Agree the authentication and holder model with Headless Domains. For existing shared-checkout purchases, use an approved buyer-authentication/delegation integration; a new local email account does not prove ownership of those names. TLD ownership and the storefront's referral link do not grant buyer authority.
  3. Keep an explicit server-side mapping from the authenticated local customer to the authorized holder/customer reference and registration/order IDs. Derive it from the session and verified records, not client-supplied identity fields.
  4. Obtain credentials scoped to the intended seller, namespaces and operations. Store them on your server. Keep wholesale costs, partner balances, upstream credentials and other customers' inventory out of customer responses. The buyer-authenticated domain-list flow uses the existing customer session; it does not require giving the storefront a Partners key. A read-only UI does not narrow the underlying session credential's account permissions.
  5. Verify inventory, expiry and DNS reads for an authorized test customer before implementing edits. Enforce per-customer authorization on every request, including reads; partner-wide API authorization is not customer isolation.

Use the correct management contract

Registration path What your agent should use or verify
Existing Headless Domains marketplace purchase The buyer's returned management link is the working default. Embedded management needs an approved registrar-channel/buyer integration; an ordinary TLD-owner key is not a substitute.
Activated legacy claim Preserve the verified holder attachment and claim-management destination. Use the approved holder-management contract; do not re-register the name or overwrite its entitlement.
Direct Partners registration Server-side GET /api/v1/registrations and GET /api/v1/registrations/{domain} on partners.headlessdomains.com, within the authenticated partner's scope. Map results to your customer before returning them. The list is bounded; do not assume one response is a complete portfolio.
Organization-bound domain Use the organization context, customer reference, grants and bindings documented in the Organization API. This is not automatic access to Partners-backed purchases.

For approved direct Partners registrations, DNS routes include GET /api/v1/registrations/{domain}/records (registration:read + dns:read) and PUT /api/v1/registrations/{domain}/records (registration:read + dns:write). DNS also requires the enabled module, matching registration and backend support. POST on that records route creates a proposed/dry-run audit; it does not apply DNS. Do not assume omission deletes a record or that all backends share replacement semantics. Read the DNS safety contract and verify the enabled adapter's behavior before presenting delete/replace controls.

Registration permission alone does not enable renewal, transfer or nameserver changes. Obtain the exact authorized route, scope, billing and status contract for each operation. Until then, show a management handoff or support action. Do not scrape the Headless Domains dashboard, replay its cookies, collect a customer's personal API key, expose service keys, or guess private endpoints to make an unsupported feature appear to work.

Payments, renewals and uncertain outcomes

If switching to partner-collected payments, confirm the commercial model first. Use server-side preflight and payment-provider verification. A browser callback saying paid is not payment evidence. Bind the verified payment amount, currency, customer, domain and term to the stored order before provisioning.

Persist each intended operation and its idempotency key before submitting it. Use that API's documented key field/header, retain the same payload and key on retry, and inspect its status contract. A timeout is not permission to charge again or create another registration. Do not assume replay guarantees from one API apply to another. Keep renewal pricing and terms explicit; do not promise auto-renewal or automatic transfers without an implemented, authorized lifecycle.

Copyable AI build brief

Copy this into the existing storefront repository. Replace the site and TLD when using it for another partner. It is an implementation brief, not a credential or permission grant.

Improve the existing tx.domains (.tx) and hey.id (.hey) registrar storefronts.
Preserve each site's branding and use Headless Domains for registry services.
Read https://docs.headlessdomains.com/guides/partner-storefronts/ first.

Mission:
Make search, checkout handoff, existing-name recovery and domain management
clear to customers. Build on the existing code; avoid an unnecessary rewrite.

Before editing:
- Inspect the repository, hosting setup, existing search and management flows.
- Read current public capabilities for tx and hey and verify API response shapes.
- Report which integration is configured: shared checkout, direct Partners or
  organization-managed. Do not treat the modes or credentials as interchangeable.
- Record supported operations and missing backend permissions separately.

Deliver Stage 1:
- Search a label or full name under the correct suffix, with live retail prices
  and supported registration terms. Never treat an upstream failure as available.
- Distinguish protected legacy names and link to the Headless Domains recovery guide.
- Preserve domain, term and supplied provider routing through shared checkout.
- Provide clear management, recovery, support and resolver-help links.
- Keep the UI accessible on mobile and keyboard, with clear loading/error states.

Then prepare Stage 2:
- Define login, recorded holder, customer mapping and recovery/exit behavior.
- Use only the approved customer/registrar/organization authority for each name.
- Start with an authenticated, customer-isolated read-only portfolio.
- Add DNS, renewal and transfer only when that registration path has an enabled,
  verified contract. Keep the working Headless Domains handoff for other actions.
- Keep all service credentials and wholesale data server-side.
- Preserve existing purchases and legacy claims; never re-register to migrate.

Verification:
- Test both suffixes, bare/full names, available/taken/protected states, timeout,
  disabled checkout, term/price changes and domain/term preservation through login.
- For management, test logged-out requests, customer A accessing customer B's
  name, revoked credentials, stale bindings, unsupported operations and retries.
- Use mocks or an approved sandbox for writes. Do not make a real purchase,
  renewal, transfer or live DNS change as a connectivity test.
- Before a live write canary, obtain the exact customer/domain/action authorization
  and any spending limit. Read back the result before claiming success.

Deliver source changes, a short setup guide, test evidence and an honest list of
remaining backend requirements. Do not describe mock UI as live functionality.
Do not change TLD custody, commercial terms or customer ownership as an incidental
frontend step. Ask Headless Domains for a missing capability rather than bypassing it.

Definition of done

A search-only release is complete when live search, truthful status/pricing, checkout handoff and management/recovery links work for both sites. A branded manager is complete only when authenticated customers can operate their own registrations through the authorized backend and cross-customer access is denied. List unsupported operations explicitly in the handoff. Keep source completion, sandbox evidence and production verification separate.