Skip to main content
Use the public testnet API at https://api.soran.domains. The resolution alias is https://resolve.soran.domains. Public /v1 routes need no API key. Payment and identity routes read current contracts. Discovery and history routes read an index, which can be incomplete or delayed. If you need to verify an answer without trusting the HTTP service and its RPC, use Universal Lookup directly.

​
Choose the right source

​
Payments and identity

The current hosted API uses Universal Lookup with contract-anchor and version checks. A failed payment read returns an error. Indexed holders, cached addresses and older records are never substituted as payment destinations.

​
Discovery and claims

Billing and marketplace services are available only when enabled on a deployment. See release status for the current network and contract addresses.

​
Conventions

  • Responses are JSON. Errors include a machine-readable error field.
  • Full-name payment inputs accept ASCII labels and lowercase ASCII uppercase letters. They reject non-ASCII input instead of applying Unicode normalization.
  • Large token amounts and generations are decimal strings where JSON numbers would lose precision.
  • Rate limits vary by deployment. Handle 429 responses.
  • Payment, records, scoped reverse, Primary and claim-fee reads send Cache-Control: no-store. Read them again before signing or paying.
  • Preparation routes return unsigned transactions. Review and sign them with the required wallet; preparing a transaction does not submit it.

​
Discovery and freshness

Paginated routes return nextCursor, hasMore, truncated and coverage. Continue with nextCursor using the same endpoint and filters. Reaching the final page means you exhausted that query’s indexed results; inspect coverage for missing or stale history. /v1/lookup?q=... returns bounded search results with truncation flags. /v1/showcase returns a curated selection of active namespaces. Neither replaces paginated namespace discovery. /v1/stats reports indexed counts. /v1/ledger/head reports the last observed chain head, which can remain cached after a failed refresh. Use /v1/coverage and status to assess freshness. GET /health checks process liveness. GET /v1/status reports component measurements. Authenticated console management is outside this public reference, apart from the tenant-facing paid claim preparation flow.

​
Submission responses

The hosted API returns the locally calculated transaction hash when a submission’s outcome is uncertain. This behavior is active in the 8 September 2026 update. Save the signed transaction and its hash before submitting. Re-broadcasting that same signed transaction preserves its identity. Preparing and signing another transaction creates a separate operation and may repeat a renewal or other action that already succeeded. notSubmitted: true also identifies a definitive pre-handler refusal or a transaction rejected before inclusion. An included failure uses notSubmitted: false; network fees can still apply. A failed preparation, an uncertain send and an included failure are different outcomes.