claimely API

01 · Fastest path

REST API

Base URL https://api.claimely.xyz. No API key needed. JSON responses with Access-Control-Allow-Origin: *, so you can call it from the browser or a server. Addresses are accepted in any case; responses use checksummed addresses. Names are lowercase label.ely.

This is the call to use for feeds and holder lists. Collect the addresses on screen, de-duplicate them, and resolve them in one request (one on-chain multicall behind the scenes). Response keys are exactly the strings you sent, so names[yourAddress] always works. null means the address has no primary name.

curl -X POST https://api.claimely.xyz/v1/reverse \
  -H 'content-type: application/json' \
  -d '{"addresses":["0xFCbed3fB642e12901664745E20fF04F35A4369F1","0x0000000000000000000000000000000000000001"]}'

{
  "names": {
    "0xFCbed3fB642e12901664745E20fF04F35A4369F1": "claimely.ely",
    "0x0000000000000000000000000000000000000001": null
  }
}

const res = await fetch("https://api.claimely.xyz/v1/reverse", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ addresses: [...new Set(traders)] }), // ≤ 200
});
const { names } = await res.json(); // { [address]: string | null }
const label = (a) => names[a] ?? `${a.slice(0, 6)}…${a.slice(-4)}`;

curl https://api.claimely.xyz/v1/reverse/0xFCbed3fB642e12901664745E20fF04F35A4369F1

{ "address": "0xFCbed3fB642e12901664745E20fF04F35A4369F1", "name": "claimely.ely" }

curl https://api.claimely.xyz/v1/resolve/claimely.ely

{ "name": "claimely.ely", "address": "0xFCbed3fB642e12901664745E20fF04F35A4369F1" }

curl https://api.claimely.xyz/v1/name/claimely.ely

{
  "name": "claimely.ely",
  "label": "claimely",
  "labelhash": "0xd04dc94e087eea0ac06d8de4b70facf59febd45c6d79431b6704202896d538ad",
  "tokenId": "94218509084093597133996286554616863271930817717212298156845629241608059041965",
  "node": "0xe0e8723de22d472a184ee6c9e32eefeb13f8174424c504bf205b27eecff42fe7",
  "owner": "0xFCbed3fB642e12901664745E20fF04F35A4369F1",
  "expires": 1825855742,
  "registeredAt": 1794319742,
  "status": "active",
  "resolver": "0xD7711E83C51a129133F3744ed2653643d3e62d3D",
  "address": "0xFCbed3fB642e12901664745E20fF04F35A4369F1",
  "primaryOf": [],
  "records": { "url": "https://claimely.xyz" }
}

Text record keys: avatar, description, url, com.twitter, com.github, org.telegram, com.discord, email. Only records that are set are returned. Timestamps are Unix seconds. status is active, grace (expired, renewable by the owner for 90 days) or expired. primaryOf lists the addresses whose primary name is this name (empty here: this owner's primary name is claimely.ely). Unregistered names return 404.

Caching, freshness and fair use

• Reverse and resolve results are read live from the chain and cached for 60 s (Cache-Control: public, max-age=60). A newly set primary name can take up to a minute to appear.
• Please batch (≤ 200 addresses per POST /v1/reverse) and cache results on your side for about 60 s. For heavy or latency-critical use, read on-chain with your own RPC (below).
• Errors are JSON: {"error": "…"} with 400 (bad input: invalid address or name, more than 200 addresses), 404, 405 (wrong method), 413 (body over 32 KB), 429 or 5xx. Treat any error as "no name" and show the short address.

Rate limits

Limits are per client IP, per minute:

Over the limit you get 429 with a Retry-After header (seconds) and {"error":"rate limited","retryAfter":60,…}. Back off and show short addresses in the meantime. API responses carry X-RateLimit-Tier: public | partner. Under heavy load, live lookups may briefly return 503 with Retry-After: 1.

IPv6 clients are limited per /64 network. Calling from Cloudflare Workers? Workers share one public bucket, so use a partner key.

curl -X POST https://api.claimely.xyz/v1/reverse -H 'x-api-key: <your key>' -H 'content-type: application/json' -d '{"addresses":["0xFCbed3fB642e12901664745E20fF04F35A4369F1"]}'

02 · No API dependency

On-chain with viem

.ely runs on the ENS v1 contract architecture, so viem's built-in ENS actions work unchanged. Add the Elysium chain with the .ely UniversalResolver. With batch: { multicall: true }, concurrent lookups are aggregated into a single eth_call. Use a recent viem 2.x (we test with 2.57).

import { createPublicClient, defineChain, http } from "viem";

export const elysium = defineChain({
  id: 99901,
  name: "Elysium",
  nativeCurrency: { name: "HYPE", symbol: "HYPE", decimals: 18 },
  rpcUrls: { default: { http: ["https://rpc.elysium.kinetiq.xyz"] } },
  blockExplorers: { default: { name: "Elysium Explorer", url: "https://elysium.kinetiq.xyz/explorer" } },
  contracts: {
    multicall3: { address: "0xcA11bde05977b3631167028862bE2a173976CA11" },
    ensUniversalResolver: { address: "0x5e17414A975008EC85A93f33143Fba8d6B807FDC" },
  },
});

export const client = createPublicClient({
  chain: elysium,
  transport: http(),               // use your own RPC URL in production
  batch: { multicall: true },      // many lookups → one eth_call
});

// address → primary name (forward-verified by the UniversalResolver)
const name = await client.getEnsName({ address: "0xFCbed3fB642e12901664745E20fF04F35A4369F1" });
// "claimely.ely" | null

// many addresses at once: still one eth_call thanks to multicall batching
const names = await Promise.all(addresses.map((address) => client.getEnsName({ address })));

// name → address
const address = await client.getEnsAddress({ name: "claimely.ely" });

// text records / avatar
const url = await client.getEnsText({ name: "claimely.ely", key: "url" });       // "https://claimely.xyz"
const avatar = await client.getEnsAvatar({ name: "claimely.ely" });             // null if no avatar record

wagmi

import { createConfig, http, useEnsName } from "wagmi";
import { elysium } from "./elysium"; // the defineChain above

export const config = createConfig({
  chains: [elysium],
  transports: { [elysium.id]: http() },
  batch: { multicall: true },
});

function Trader({ address }: { address: `0x${string}` }) {
  const { data: name } = useEnsName({ address, chainId: elysium.id });
  return <span>{name ?? `${address.slice(0, 6)}…${address.slice(-4)}`}</span>;
}

Pass chainId: elysium.id (wagmi) or use an Elysium client (viem). Without it, lookups go to Ethereum mainnet ENS. The public RPC is rate-limited per IP. Use your own endpoint for backends.

03 · Elysium, chain id 99901

The contracts

All contracts are verified on the Elysium explorer. Deployed at block 4056527.

Key hashes: namehash("ely") = 0x3be82acffc98307c4d985a244620d3bb2ae087e06446863fd2c64d5925b06d55, reverse names live under addr.reverse (coin type 60, the EVM address).

04 · Showing names

Display guidelines

• Always use the reverse lookup (POST /v1/reverse, /v1/reverse/:address, or getEnsName) to label an address. It returns a name only if that name's address record points back to the same address (forward-verified), so it can't be spoofed by someone pointing their reverse record at a name they don't control.
• Don't label an address with a name it merely owns. A wallet can own many names; only its primary name is its identity.
• Fall back to a short address such as 0xFCbe…69F1 when the result is null or on any error. Never block rendering on the lookup.
• Show the full name including .ely. If space is tight, truncate the middle of the label (verylongna…me.ely), not the suffix.
• Keep the address one click away (tooltip, copy button or explorer link: https://elysium.kinetiq.xyz/explorer/address/<address>).
• Cache for about 60 s and refresh on user action. Names can change when owners update their primary name or a name expires.

Reference

More endpoints