Profiles, identity and discovery

A Soran name can give your application a profile as well as a receiving address. Read a holder’s avatar, description, website and social handles, then combine them with an elected display name. The same identity records work for supported subnames such as work.alice.nova. Start with a configured Lookup client. The profile concept explains the roles; the holder guide shows how people publish their information.

Read a profile

import { PROFILE_KEYS } from "@sorandomains/lookup";
// org, url, email, description, avatar, location, twitter, github
const profile = await soran.profile("alice.nova");
console.log(profile.avatar, profile.description, profile.twitter);

const identity = await soran.identity("alice.nova");
console.log(identity.details, identity.profile);

Values come from text records published by the current holder. Prior ownership generations do not appear. This establishes who published a value, not verified ownership of an external social account or a real-world identity. Escape text for display and validate URL schemes before making links. Use text(name, key) for other keys. Keys are not globally enumerable. They must be nonempty Soroban Symbols of at most 32 bytes. Lookup returns at most 4,096 UTF-8 bytes per value; oversized historical text throws instead of being truncated.

Combine identity reads

Method	What it combines	Behavior
`identity(name)`	Name details, profile and holder/recipient/namespace-owner display names	Details and profile failures throw; optional display-name enrichments can be `null`
`walletProfile(address)`	Primary, scoped reverse names, first holdings page and Primary’s profile	Continue holdings with `holdings.nextCursor`

Display names are explicit elections, separate from holding a name. These aggregates perform several reads and are not one atomic ledger snapshot.

Holdings pages

const page = await soran.namesOfPage(address, { limit: 40 });
console.log(page.names);
console.log(page.coverage, page.verification);
if (page.hasMore) {
  const next = await soran.namesOfPage(address, { cursor: page.nextCursor!, limit: 40 });
}

Request a page for a G or C holder address. The default limit is 40; you can request 1–100 candidates.
Render the verified names and keep the page’s verification and coverage information.
When hasMore is true, pass nextCursor to the next request.

Discovery needs a configured hintUrl. The indexer supplies candidates; in universal mode, the SDK verifies their current holder and activity through Lookup. Failed checks are distinct from proven stale or nonheld candidates.

Field	Meaning
`nextCursor`, `hasMore`	How to continue candidate discovery
`verification`	Counts of candidates, verified names, exclusions and failed checks
`coverage`	Indexer’s processed/head ledgers and known gaps, or `null`
`complete`	Final page, indexer reports complete coverage, and no candidate verification failures

Coverage is the indexer’s report; it cannot prove that the indexer omitted nothing. complete describes this page’s completion conditions, not an independent proof of every holding. namesOf(address) aggregates up to 1,000 candidates and throws INCOMPLETE for partial results. Use namesOfPage when your interface needs to display partial results or continue beyond that bound.

Address type and holdings

walletProfile(mAddress) reads display names elected for that exact M route through the muxed identity extension. It preserves the complete M address and does not substitute the base G account.

Input and configuration	`walletProfile.names`	`walletProfile.holdings`
G/C address with `hintUrl`	First page’s verified names	First `NamesPage`
G/C address without `hintUrl`	`null`	`null`
M address	`null`	`null`

An M routing ID is not a name holder. namesOf and namesOfPage accept G/C holder addresses only. Holder and namespace-owner identity also use their G/C accounts.

Read history

history(name) returns up to 100 indexed events with transaction and ledger references. Use the HTTP history and events cursors for durable pagination. History needs hintUrl and is informational. Contract expiry timestamps do not provide a complete registration timeline. Event time differs from ingestion time, and historical issuance metadata can be unknown.

​Read a profile

​Combine identity reads

​Holdings pages

​Address type and holdings

​Read history

Read a profile

Combine identity reads

Holdings pages

Address type and holdings

Read history