Resolver API

api.arcns.io, the read-only ArcNS resolver API. Every route with its real response fields, the status contract (404 is proof of absence, 502 is an outage), caching, CORS, rate limits, and how to run your own instance.

https://api.arcns.io is a read-only resolver for @handle, .arc and .circle names. It holds no keys and no database: every data route reads Arc testnet over JSON-RPC at one pinned block and returns what the contracts say. It exists for callers that cannot run an EVM client in-process (a recipient field in a wallet, an explorer row, a bot). The SDK never depends on it.

Routes

Only GET, HEAD and OPTIONS are accepted (405 otherwise). @ must be URL-encoded as %40 in a path: /resolve/%40nike. A path segment longer than 256 characters or with malformed percent-encoding is 400. Any other path is 404 {"error":"not found","input":"/…"}.

Try it: what the API guarantees today

curl -s https://api.arcns.io/health

{  "ok": true,  "service": "api",  "version": "0.1.0"}

Status contract

Every error body is {"error": "<message>", "input": "<what you sent>", …} with route-specific extras. A 502 is never cached and must never be treated as "free". A 404 is the only answer that means absence.

GET /resolve/:name

@handle (200):

{
  "input": "@nike",
  "name": "@nike",
  "namespace": "handle",
  "registry": "0x…",
  "resolver": "0x…",
  "chainId": 5042002,
  "blockNumber": 60812722,
  "epoch": 3,
  "owner": "0x…",
  "addr": { "coinType": 2152525650, "address": "0x…", "verified": true },
  "tokenized": true,
  "locked": false,
  "handleType": "Human",
  "expires": null
}

.arc / .circle (200):

{
  "input": "nike.arc",
  "name": "nike.arc",
  "namespace": "arc",
  "chainId": 5042002,
  "blockNumber": 60812722,
  "source": "arcns",
  "registry": "0x…",
  "ensRegistry": "0x…",
  "resolver": "0x…",
  "owner": "0x…",
  "addr": { "coinType": 2152525650, "address": "0x…", "verified": true },
  "epoch": 3,
  "expires": null
}

Field notes:

• namespace is handle, arc or circle. registry is the contract that holds the name: the HandleRegistry for a handle, the TLD's registrar for a TLD name. source labels which product's registry answered (arcns, or the pinned peer khenzarr/arcns).
• owner is the controller (ownerOf / registry owner(node)). It is never used as a payment address. addr is the only payment address and is null for a name whose owner has not set a record.
• addr is the Arc record (ENSIP-11 coin type 2152525650), falling back to the coin-type-60 record; verified is true only when the owner proved control of that address on chain. See Verified records. A record from the peer registry is always the coin-type-60 record with verified: false.
• epoch is the name's ownership epoch; records from an older epoch are never returned. It is null when the name's resolver is not the ArcNS resolver.
• expires is null for a permanent registration. handleType is Human, Merchant, Org or Agent. tokenized and locked are handle flags.
• sunset: { "sunsetAt": … } is present while a TLD is inside its sunset window and still resolving.
• candidates is present on a 200 when more than one pinned registry holds the name and they agree; each candidate carries the full per-registry answer above.

Not registered (404): the body proves what was consulted.

{
  "error": "name not registered",
  "input": "zzqx7k2mfresh.arc",
  "name": "zzqx7k2mfresh.arc",
  "namespace": "arc",
  "chainId": 5042002,
  "blockNumber": 60812722,
  "registriesConsulted": [
    { "source": "arcns", "registry": "0x…" },
    { "source": "khenzarr/arcns", "registry": "0x…" }
  ]
}

Registries disagree (409): every registered candidate, nothing chosen.

{
  "error": "conflict: registries disagree",
  "input": "alice.arc",
  "name": "alice.arc",
  "namespace": "arc",
  "chainId": 5042002,
  "blockNumber": 60812722,
  "candidates": [ { "source": "arcns", "registry": "0x…", "owner": "0x…", "addr": { … }, … }, { "source": "khenzarr/arcns", … } ]
}

Render every candidate with its source and registry and let the user choose. Never auto-select.

GET /reverse/:address

{
  "input": "0xce42…54AC",
  "address": "0xce42…54AC",
  "name": "alice.arc",
  "namespace": "arc",
  "registry": "0x…",
  "chainId": 5042002,
  "blockNumber": 60812722,
  "epoch": 3,
  "verified": true
}

There is one primary per address across every namespace. It is returned only after forward confirmation: @x requires ownerOf(tokenId) == address; x.arc / x.circle requires the name's Arc record (then coin type 60) to equal the address in our registry. Otherwise: 404 no primary set, 404 primary is stale (forward record does not match) (with the stale primary in the body), or 404 primary is not a known name shape. 400 invalid address for anything that is not a 20-byte hex address. verified on this route is always true because the answer exists only when the forward check passed.

GET /nft/:name

ERC-721 metadata for a registered @handle or first-level .arc / .circle name: name, description, image (a self-contained data:image/svg+xml;base64,… card), external_url, and attributes (Namespace, Handle Type for handles, Tokenized, Rarity, Bucket, Length, Registry). The body also carries the provenance fields every answer has: chainId, blockNumber, registry, namespace, input. A subname answers 404 subnames have no token.

GET /version

{
  "service": "api",
  "version": "…",
  "chainId": 5042002,
  "rpc": "rpc.testnet.arc.io",
  "head": { "number": 60812722, "timestamp": 1757200000, "ageSeconds": 2 }
}

rpc is the host only, never the path or query where provider credentials would live. This route reads the head, so it answers 502 when the RPC is down or stale, which makes it a truthful probe; /health is process liveness only.

Caching

• Cacheable statuses (200, 404, 409, 410) are served with cache-control: public, max-age=5. Everything else is no-store.
• The server keeps its own response cache for at most 5 seconds, keyed on the path and the chain head block number, so an answer can never outlive the block it was read at; an ownership change is a new block and therefore a new key.
• The head itself is re-read at most every 2 seconds and every route reads at that pinned block. A head older than 30 seconds is 502.
• 502 is never cached, by construction: the head is read before the cache is consulted, and a head failure never reaches it.

CORS

access-control-allow-origin: * on every response; OPTIONS answers 204 with access-control-allow-methods: GET, OPTIONS. There is no write path and no key for a cross-origin caller to reach.

Rate limits

A per-client token bucket: 20 requests per second sustained, burst 60. A limited request answers 429 {"error":"rate limited"} with retry-after: 1. The client is the socket address, or cf-connecting-ip when the instance runs behind the tunnel with API_TRUST_PROXY=1. Above 128 requests in flight the instance answers 503 server busy immediately rather than queueing. Bulk consumers should read the chain directly with the SDK or run their own instance.

Run your own instance

The API is the api/ directory of fortiblox/fortiblox-arcns (MIT). It is a Node 24 service with a single runtime dependency (viem), built into a node:24-bookworm-slim image that runs as an unprivileged user and health-checks itself with curl http://127.0.0.1:8812/health.

git clone https://forgejo.selfhsted.com/fortiblox/fortiblox-arcns
cd fortiblox-arcns/api
npm ci && npm run build && npm start        # or: docker compose -f ../api/compose.yml up

Configuration is environment only. Every problem is reported in one message at boot, and the service binds its socket only after eth_chainId matches ARC_CHAIN_ID, so a misconfigured instance never looks healthy.

Contract addresses have no defaults: a defaulted address is one an attacker can substitute. Take the values from the deployment file described on the Contracts page once it is published.

Questions

Questions: [email protected].