Skip to main content
Use these routes to discover namespaces and names. Results come from the index; verify current ownership, identity and payment instructions through current reads.

​
Find namespaces

Returns namespaces, nextCursor, hasMore, truncated and coverage. Each namespace includes: Results are ordered by namespace label. limit is 1–100 and defaults to 100. activated is an indexed setup indicator; it does not verify that every dependent contract is currently available.

​
Find holder candidates

Accepts G or C holder addresses and defaults to 20 entries. The response includes address, source: "holder_hint", verified: false, filtered, entries and pagination/coverage fields. Each entry contains name, namespace and namespaceDisplay. Entries are ordered by name ID. These names are holder candidates, not elected reverse names. Use scoped reverse or Primary for display identity.

​
Read the hosted directory

Returns filtered, namespaces and pagination/coverage fields. Each namespace contains label, displayName and a nullable logo. Treat uploaded display names and logos as untrusted presentation content. This route defaults to 100 entries, ordered by label. It can apply the subscription filter described below; /v1/namespaces does not apply that filter.

​
Billing filter

When billing enforcement is enabled on a deployment, directory routes may include only namespaces with an active subscription. filtered: true means that policy filter was applied. filtered: false means no subscription filter was applied. Either result can still be paginated or have incomplete indexing coverage. Directory presence does not gate on-chain forward resolution. If you know a name, resolve it directly. Hosted service expiry does not revoke a namespace.

​
Pagination and errors

All three routes accept a limit from 1 to 100. Pass nextCursor back as cursor until hasMore is false, using the same endpoint and filters. Cursors are opaque and scoped to the query. Inspect coverage even after reaching the last page. Invalid pagination returns 400 bad_cursor or 400 bad_pagination. The reverse directory returns 400 invalid_account for an invalid address or an M address. For holdings with indexed lifecycle details, use holdings pages. Verify their current holder and activity through Lookup metadata.