Skip to main content
The Soran API is the HTTP counterpart to the SDK: a hosted read mirror of on-chain state, plus a hints layer the SDK can verify. Use it when you want resolution, name records, the directory, or marketplace listings from a backend without running Soroban RPC simulations yourself.

​
Base URL

The base URL is deployment-specific — each Soran deployment serves its own API host. Use the base URL published by the deployment you integrate with; every path in these docs is relative to it.

​
What the API is (and isn’t)

The public API is a read mirror, not the source of truth. It serves an indexed projection of the contracts — fast, cacheable, and convenient — but the chain is authoritative.
  • Trust-sensitive reads should be verified. The SDK treats API answers (reverse lookup especially) as untrusted hints and re-verifies them against the contracts over Soroban RPC. If you consume the API directly from a backend, apply the same discipline for anything that gates money: confirm the resolution on chain before sending funds.
  • Convenience reads can be trusted casually. Browsing listings, showing a directory, rendering a status page — the mirror is fine as-is.
Authenticated console endpoints (namespace management, issuance, billing, the seller side of the marketplace) exist under separate paths but are out of scope for these docs — they back the hosted console. Everything documented here lives under /v1 and needs no credentials.

​
Access

  • No API key. Every /v1 endpoint is public and unauthenticated.
  • Open CORS. /v1/* and /health allow any origin, so you can call them straight from a browser.
  • Rate limits. A global per-IP limit applies (600 requests per minute by default; operators can tune it), and sensitive routes carry tighter per-route buckets — for example, minting a marketplace deposit intent is limited to 10 per minute per IP by default. Exceeding a limit returns 429.

​
Conventions

  • All responses are JSON.
  • Names are lowercase; name paths take the namespace and label as separate segments: /v1/resolve/{namespace}/{label} resolves label.namespace.
  • Errors return a machine-readable code, optionally with a human-readable detail:
  • Server-side failures return a generic 500 body — internals are never serialized to the client:
  • Several responses include a ledger field, and its meaning is per-endpoint. On /v1/status, /v1/allocations, and /v1/stats it’s the chain ledger the mirror has observed — useful for judging freshness — and GET /v1/ledger/head returns it on its own. On /v1/resolve, ledger is different: it’s the ledger the name was issued in, not the observed head.

​
Endpoint map

Resolution

Resolve names, read full name records and resolver record sets, reverse-lookup an address.

Directory

The cross-tenant reverse directory: every name an address holds, across all of Soran.

Marketplace

Browse namespace listings, mint a deposit intent, read escrow-settled sale history.

Status & allocations

Component health with honest freshness signals, plus the public namespace claim queue.

​
Discovery endpoints

Five small endpoints round out the read surface:
  • GET /v1/namespaces — the public namespace list: label, display name, policy, whether it’s activated, and when it was awarded (bounded to 500).
  • GET /v1/namespaces/{namespace} — one namespace’s record: operator account, policy, on-chain node, award ledger, issued-name count.
  • GET /v1/lookup?q={query} — whois-style search across namespaces and names (up to 8 of each; the query is capped at 64 characters).
  • GET /v1/showcase — the most-active namespaces (up to 12, ranked by issued-name count) with their logos and name counts — built for landing-page grids.
  • GET /v1/stats — headline counts: total namespaces, total names, and the observed chain ledger.

​
Health

GET /health returns { "ok": true, "service": "soran-api" } — a liveness probe only. For real component health, use /v1/status.