Doma API: register and trade DNS-compliant on-chain domains

Doma Protocol (doma.xyz) bridges traditional DNS registrars and on-chain ownership. Domains stay ICANN/DNS-compliant while gaining tokenized, multi-chain representations — not an alternative root.

API surface: docs.doma.xyz/api-reference (llms.txt). GitHub: github.com/d3-inc. X: @domaprotocol.

Architecture (three layers)

Registrar bridge — APIs for registrars to sync events bidirectionally with Doma Chain
Doma Chain — authoritative domain state; cross-chain messaging (docs cite ERC-7786); EVM + SVM-oriented ops
On-chain capabilities — tokenization, synthetics, DomainFi on chains including Base, Solana, Avalanche, Ethereum

Registrars keep customer relationship, DNS, and ICANN compliance; Doma is the “integrate once, distribute everywhere” token layer.

API reference map

docs.doma.xyz/api-reference
Section	Role
Authentication and Rate Limits	`Api-Key` header; keys from Developers; ~10 req/s default
Domain Registration	Primary register flow: GraphQL + on-chain voucher payment
Smart Contracts API	EVM proxy record / name token contract APIs
Multi-Chain Subgraph	Indexed reads across chains
Poll API	Polling patterns for async state
Orderbook API	Marketplace orderbook
Network Information / Deployed Contracts / TLDs	Chain IDs, RPCs, addresses, supported TLDs
Fractionalization	Shared ownership / liquid domain patterns

Auth

bash

# Key from https://app.doma.xyz/account/developers
curl -sS "https://api.doma.xyz/graphql" \
  -H "Content-Type: application/json" \
  -H "Api-Key: $DOMA_API_KEY" \
  -d '{"query":"{ __typename }"}'

# Testnet GraphQL (docs)
# https://api-testnet.doma.xyz/graphql

Higher rate limits: contact Doma support (docs link to D3 service desk). Do not put API keys in client bundles.

Domain registration flow (API + chain)

From Domain Registration. Use this for a new name (primary). Already own a DNS domain? See “How to tokenize a domain” instead.

Search & price — availableDomains, domainPricing
Registrant handle — upload WHOIS contacts (email verification or privileged pre-verified path)
Create order — createOrder returns a backend-signed payment voucher
Pay on-chain — pay(voucher, signature) on the Marketplace contract (token + amount + paymentContractAddress from voucher)
Track order until name token mints to the paying wallet

You do not EIP-712-sign the voucher yourself — Doma signs it; the wallet only submits payment. Runnable example: d3-inc/doma-register-example (viem + graphql-request).

Network details (docs snapshot)
	Testnet	Mainnet
GraphQL	`https://api-testnet.doma.xyz/graphql`	`https://api.doma.xyz/graphql`
Chain ID	97476	97477
RPC	`https://rpc-testnet.doma.xyz`	`https://rpc.doma.xyz`

Prerequisites: funded EVM wallet (gas + USDC or native fee currency per quote); accessible email if using verification path.

Agent surfaces (related docs)

Beyond REST/GraphQL, docs cover agentic commerce: MCP server, AgentRoot skills, Doma CLI, agentic wallet, secondary sales / MPP skills. Use those when the integrator is an agent, not a classic web app.

When to use

Fit
Use Doma	Not this
Real DNS names with on-chain ownership / DomainFi	Pure alt-root / app-only names with no ICANN DNS
Registrar-integrated tokenization	Single-registrar closed NFT without DNS bridge
Programmatic register + marketplace	Manual-only registrar UI with no API key

Summary

Doma’s API reference is how builders register and operate DNS-real domains on-chain: authenticate with Api-Key, drive GraphQL for search/order/WHOIS, pay a signed voucher on Doma chain, then index via subgraph/orderbook. Start on testnet GraphQL + RPC, clone the register example, then expand to marketplace and agent MCP tools.