/v1/payment when sending a payment. Use records and identity routes for profiles, and holdings routes to discover names that you can then verify on chain.
All routes below use the public API base URL. For addresses on other blockchains, use the separate network address routes.
Name routes accept a relative child label such as pay.alice: /v1/payment/nova/pay.alice resolves pay.alice.nova. The namespace needs compatible subname contracts and a policy that permits resolution. Use the subname API for creation, policy and child listings.
Complete payment
address and memo:
memo: { "type": "none" }.
Use the exact returned address and memo together. The API reads current contracts and returns an error if it cannot obtain a valid destination. See payment destinations for memo limits and transaction examples.
Address-only convenience
name, account, storage: "live" and optional indexed fields ownership, expires_at and ledger.
account is the effective memo-free G or C payment destination. It may differ from the holder. A required memo returns 409 memo_required; an M destination returns 409 muxed_destination. Use /v1/payment in either case.
The optional indexed fields can be null. ledger is the issuance ledger, not the current chain head. storage: "live" describes the successful read and does not promise future storage availability.
Current records
This response includes those two profile fields. Use Lookup
profile(name) for the standard profile schema, including description, organization, location and social handles.
The identity fields are comparisons against this name:
Despite its name,
primaryName is not a name string. A successful read can return false because it found another Primary or no verified election. See the limits of absent Primary answers.
For an M destination, both address fields retain the complete M string. Identity comparisons use its exact base G account and routing ID. They do not inherit the base account’s display name.
Payment, metadata, profile text and scoped reverse reads must succeed. These separate reads are not one atomic snapshot. A Primary error is the exception: the response preserves the other fields and exposes that error through primaryStatus.
Read failures
These current-read routes use
Cache-Control: no-store. Never convert a failed read into a memo-free destination.
Exact name record
name, namespace, holder, builtinAddress, decimal-string generation, expiresAt, active, ownership policy and operator. The response marks these chain reads with source: "chain" and verified: true.
For a child, the response also includes child: true, parent, subnamePolicy and ownership: "parent". The holder is the parent holder. A child’s policy-dependent activity does not create independent transfer or renewal rights.
issuedAt, issuedLedger and txHash are historical enrichments. They become null when the indexed holder or generation does not match current state. historyPending indicates incomplete current-generation issuance history. Index failure does not replace current ownership with a cached value; failed chain reads remain errors.
Use this route for ownership displays. builtinAddress may differ from the effective Resolver destination; use /v1/payment for receiving instructions.
Verified reverse and Primary names
address, name, source, verified and proof. Scoped reverse also returns namespace.
A nonempty
name is a current contract-verified election. When no verified election is returned, name is null, verified is false, and proof is "no_current_verified_election". This does not always prove that no stored declaration exists; see absence and failures.
For M addresses, Lookup reads reverse_muxed or primary_name_muxed with the exact base G account and u64 routing ID. Invalid addresses return 400. Unsupported muxed identity returns 409; failed or malformed dependent reads return 503. Both routes use Cache-Control: no-store.
Indexed holder hint
name, source: "holder_hint", verified: false and coverage. It returns 404 no_name if there is no matching indexed row.
Use this route only as a discovery hint. A holder’s G/C address is not the same as an M routing identity, and this route does not establish reverse identity. Prefer scoped reverse or Primary when displaying an elected name.
Prepare an M display-name transaction
reverse: "set", reverse: "clear", primary: "set" or primary: "clear". Do not combine actions. destination is the complete M address. The optional address field is its base G signer and defaults to that account. The name supplies the namespace when clearing reverse.
A successful response contains ok, unsigned xdr, signer, destination, Lookup contract, method and network. Setting an election requires a matching current M destination; setting Primary also requires a matching M reverse election. This request does not change the name’s payment destination.
Before signing, validate the network, Lookup and Registry anchors, method, name or namespace, base G account, routing ID, authorization and network-fee ceiling. The base G account must sign, including when a custodian controls it. Preparation does not save the election.
You can also build these calls with the Holder SDK.
Holdings pages
holder, names, nextCursor, hasMore, truncated and coverage, ordered by name ID ascending. limit is 1–100 and defaults to 100.
Follow nextCursor until pagination is complete, then inspect coverage. These are indexed candidates: verify each current holder and active state through Lookup metadata, or use SDK namesOfPage.
To enumerate a parent’s child labels, use the on-chain subname listing. Its offset pagination and historical child records differ from this indexed holdings route.
Invalid addresses return 400 bad_address. Invalid pagination returns 400 bad_cursor or 400 bad_pagination.
Name history
404 name_not_found here does not prove that the child is unregistered. Check current metadata or the subname API for its state.