Quickstart - Soran

Resolve a Soran name into its complete payment instructions, then recheck them before sending. Reading requires no wallet or signing key. You need Node.js 22.12 or newer and a JavaScript or TypeScript project. This guide uses Lookup 0.11.0, Stellar SDK 17, and the current testnet deployment. By the end, you will have a complete Stellar payment destination and know how to read the name’s ownership and identity.

Configure one shared reader

Install Lookup 0.11.0 with Stellar SDK 17:

npm install @sorandomains/lookup@0.11.0 @stellar/stellar-sdk@^17

Supply the current Registry, Lookup and Primary together:

import { Soran } from "@sorandomains/lookup";

const soran = new Soran({
  network: "testnet",
  registryId: "CCSORANDPQINYOYB5SVO45WJP2LBBYKC72HHUIRVXB4J6RUZKDAUW7G4",
  lookupId: "CDSORANQAJK35UV2HR63CMB6M5NYISHMUBTB6EQY2CZ3Y7HJDIOHRJWA",
  primaryId: "CCSORAN7Y7ICQK2MBSVCJT3BUN5EHXKDKSTMGVB6QWSYXWMMLG2WIFJ6",
  reverseNamespaces: ["nova"],
});

Universal Lookup is the default shared reader. It checks the namespace’s current on-chain routing and finds its Resolver for you. A missing Lookup configuration throws CONFIG.

Read the whole payment instruction

Start with a live testnet name. Read its address and memo together:

const payment = await soran.resolvePayment("Alice.Nova");
console.log(payment.address, payment.memo);

What you get: a Stellar address and a memo object. The memo type is none, id, text, or hash. Keep the returned pair together; an address alone can leave out required routing information. Display both fields for review. Near the user’s confirmation, recheck that the instruction has not changed:

if (!(await soran.verifyPayment("alice.nova", payment))) {
  throw new Error("Payment instructions changed; review them again");
}

Preserve both fields when constructing the payment. If the memo type is id, text or hash, include its exact type and value. Refuse to send if your payment flow cannot carry it. Memo IDs are decimal strings; never convert them to JavaScript numbers.

Address	How to use it
`G...` account	Use a classic Stellar payment and the returned memo, if any.
`M...` muxed account	Use the full M address in a compatible payment flow. Its embedded ID remains part of the destination; the memo is `none`.
`C...` contract	Use the appropriate contract/token transfer flow. The memo is `none`.

A Soran memo of none does not override an account’s memo-required setting. A classic transaction has only one memo, so split payments that need different memos. Never strip an M address to G or turn its embedded ID into a transaction memo. See payment destination examples. A successful read is a point-in-time answer. Rechecking catches stale client data; it cannot prevent a later record change before a separate payment settles.

Read ownership and display names separately

const name = await soran.nameMetadata("alice.nova");
const namespace = await soran.namespaceMetadata("nova");
const displayName = name ? await soran.primaryOf(name.holder) : null;

nameMetadata can return null. When a record exists, holder identifies its owner and builtinAddress is its Registrar target. Either can differ from the effective payment address. Primary and reverse names identify an account; they do not identify an individual customer memo on a pooled exchange account. Use namespace assurance to assess Resolver provenance. It does not freeze holder records or remove Lookup governance and RPC trust.

Choose your next step

Read profiles

Load the avatar, description, and links a name’s holder publishes.

Resolve other networks

Request the address for an explicitly selected network.

Work with subnames

Read child names and understand their parent-bound ownership.

Offer usernames

Integrate eligible username claims into your own application.

For more control, read payment semantics, SDK configuration, or the direct contract ABI.

​Configure one shared reader

​Read the whole payment instruction

​Read ownership and display names separately

​Choose your next step