Name service endpoints

Resolve ENS and SuiNS names to SPECTER meta-address payloads

Resolve ENS

GET /api/v1/ens/resolve/:name returns ENS + meta-address details.

Resolve SuiNS

GET /api/v1/suins/resolve/:name returns SuiNS + meta-address details.

Endpoints

• GET /api/v1/ens/resolve/:name
• GET /api/v1/suins/resolve/:name

Resolution behavior

1. Read name service record

   ENS checks specter text record first and falls back to ENS content hash when needed. SuiNS reads content hash.

2. Extract CID and fetch from IPFS

   Resolver parses CID formats (ipfs://, /ipfs/, raw CID) and downloads raw bytes from configured gateway.

3. Decode and validate

   Backend decodes bytes into MetaAddress and validates key structure before responding.

Request params

name · string · required

ENS name like alice.eth or SuiNS name like alice.sui.

no_cache · string

Supported on SuiNS resolve endpoint. If present, clears resolver cache before lookup.

Response schema

meta_address · string · required

Hex-encoded SPECTER meta-address.

spending_pk · string · required

Hex-encoded spending public key.

viewing_pk · string · required

Hex-encoded viewing public key.

ipfs_cid · string

CID where meta-address bytes were fetched.

ENS-specific response field

ENS responses include ens_name.

SuiNS-specific response field

SuiNS responses include suins_name.

Example calls

ENS

curl -s "http://localhost:3001/api/v1/ens/resolve/alice.eth" | jq .

SuiNS

curl -s "http://localhost:3001/api/v1/suins/resolve/alice.sui?no_cache=1" | jq .

JavaScript

const ensRes = await fetch("http://localhost:3001/api/v1/ens/resolve/alice.eth");
const ensData = await ensRes.json();
console.log(ensData.meta_address);

Name-service lookups are always fresh. IPFS downloads can be cached by CID in resolver clients.