Developer Docs

Build on ANS with a clear integration path

This page covers production integration for ANS V2, including read and write methods, indexing strategy, pricing behavior, failure handling, and launch checklist.

User Docs MetaMask Snap Docs

Network and contracts

ANS runs on Abstract mainnet. These constants should be pinned in your integration so lookups and writes always target the right chain and contract.

Chain

Abstract mainnet (chain ID 2741)

Top-level domain: .abs

Core contract

0x86a282845a61302Ba4735d111b1a1417f6e617Ad

Open on ABScan

ANS resolution and ownership are enforced by on-chain smart contracts. Treat on-chain reads as the source of truth, not off-chain caches.

Official SDK (npm, pnpm, yarn, Vite)

ANS now provides an official TypeScript SDK so teams can integrate reads, writes, events, and prepare-only registration flows with fewer moving parts across wallets, apps, and indexers.

Install (npm)

npm install @ans-abstract-name-service/sdk viem

Install (pnpm)

pnpm add @ans-abstract-name-service/sdk viem

Install (yarn)

yarn add @ans-abstract-name-service/sdk viem

Availability checks

Use isNameAvailable(name) before registration flows or search handoff.

Discovery reads

Use getAllNames() and getSubdomainRoots() for dashboards, admin tools, and indexing jobs.

Prepare-only writes

Use prepareRegisterTransaction() when your app or agent should build calldata and value without signing immediately.

Minimal Vite/TypeScript setup

import { createAnsClient } from "@ans-abstract-name-service/sdk";
import { createPublicClient, createWalletClient, custom, http, defineChain } from "viem";

const abstract = defineChain({
  id: 2741,
  name: "Abstract",
  nativeCurrency: { name: "ETH", symbol: "ETH", decimals: 18 },
  rpcUrls: { default: { http: ["https://api.mainnet.abs.xyz"] } },
});

const ans = createAnsClient({
  publicClient: createPublicClient({ chain: abstract, transport: http() }),
  walletClient: createWalletClient({ chain: abstract, transport: custom(window.ethereum) }),
});

const owner = await ans.resolve("luca.abs");
const available = await ans.isNameAvailable("newname.abs");
const roots = await ans.getSubdomainRoots();

The SDK wraps common flows such as resolve, registerWithPriceUpdate, registerWithCouponAndPriceUpdate, setRecord, setTextRecord, transferDomain, migration, event watchers, name enumeration, and prepare-only transaction building.

Backend private-key flow: pass a viem Account object (for example privateKeyToAccount) instead of only an address string.

This forces raw signed transactions (eth_sendRawTransaction) and avoids 403 "rpc method is not whitelisted" RPC errors.

Prepare transaction data without signing

Use this helper when you want the SDK to return calldata, function args, and the total required value before the wallet or agent executes the transaction.

const prepared = await ans.prepareRegisterTransaction({
  name: "newname.abs",
  account,
  priceUpdateData,
});

console.log(prepared.functionName);
console.log(prepared.args);
console.log(prepared.value.toString());

Pyth Oracle Configuration (SDK defaults)

ANS SDK defaults to the ETH/USD Pyth feed used by ANS V2 pricing. You can use defaults or pass a custom feed ID and Hermes URL when needed.

Default Hermes URL

https://hermes.pyth.network

Default ETH/USD Price ID

0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace

Example: fetch priceUpdateData with the SDK default feed before register.

import { fetchPythUpdateData, DEFAULT_PYTH_ETH_USD_PRICE_ID } from "@ans-abstract-name-service/sdk";

const priceUpdateData = await fetchPythUpdateData(DEFAULT_PYTH_ETH_USD_PRICE_ID);

const quote = await ans.quoteRegisterValue({
  name: "newname.abs",
  account,
  priceUpdateData,
});

Use this exact flow to avoid pulling update data from the wrong feed.

ANS MCP Server

ANS also ships as an MCP server. AI tools can resolve names, inspect records, quote registrations, and prepare agent identities without writing custom integration code first.

Example agent identity: name.agent.abs

Remote endpoint

https://AbsNameService.xyz/api/mcp

This endpoint is for MCP clients such as Codex, Claude, Cursor, and VS Code. It is not meant to be opened directly as a normal browser page.

Main capabilities

Resolve names and reverse records
Inspect owner names, records, and profile fields
Prepare registration flow for agent identities

Install examples

codex mcp add ans --url https://AbsNameService.xyz/api/mcp

Full client-specific setup examples live on the dedicated MCP page.

Open ANS MCP Page Register a Name

Integrations showcase

Projects that integrated ANS into live products.

MyAbs

Visit

Profile and identity platform with ANS resolution support.

Tollan Universe

Visit

Action Roguelike RPG with high stakes competitive gameplay. Survive countless waves of enemies, acquire elemental powers and defeat deadly bosses to secure your place on the leaderboard!

Riftborn

Visit

Wave-based monster slaying game built on Abstract.

Rafflart

Visit

NFT raffle platform with on-chain escrow and transparent winner draws.

User Docs

For onboarding and user-facing flows such as registering and managing names.

Open User Docs

Developer focus

Method reference, event indexing, and production safeguards for dApps and wallets.

Jump to Read Methods

Recommended integration architecture

Read layer

Use direct contract reads for resolve and reverse lookup. Cache responses, but always allow refresh after writes.

Write layer

Handle registerWithPriceUpdate, registerWithCouponAndPriceUpdate, setRecord, setTextRecord, and transferDomain with clear status states and transaction hashes.

Indexing layer

Index key events to keep local search and profile screens synchronized with on-chain state changes.

Read methods reference

These methods should cover most user-facing reads in wallets, explorers, and profile pages.

getAddress(name)

Resolve name to owner address

Input is case-insensitive because names are normalized to lowercase in contract logic.

records(name)

Read the primary record string

If the record contains an address format, ANS also maintains reverse lookup mapping.

textRecords(name, key)

Read text profile values

Allowed keys include twitter, discord, avatar, url, and email.

getNameByAddress(address)

Reverse lookup from address to name

Useful for showing a preferred name in wallets and transaction activity.

price(name)

Estimate payable registration amount

Price depends on label length, optional discounts, and oracle conversion.

getDomainsByOwner(owner)

Fetch names owned by one address

Good for dashboard screens where users manage multiple names.

Write methods reference

Handle these writes with strong UX around confirmations, failures, and pending states.

registerWithPriceUpdate(name, priceUpdateData)

Registration path that updates oracle price feed in same flow.

registerWithCouponAndPriceUpdate(name, couponCode, priceUpdateData)

Registration with coupon discount and oracle price update in same flow.

setRecord(name, record)

Sets a record and can update reverse lookup tracking.

setTextRecord(name, key, value)

Sets profile records for allowed keys.

transferDomain(name, to)

Transfers ownership and updates owner-linked mappings.

migrateFromOldContract(oldTokenId, newName)

Migrates eligible V1 names to V2.

Name parsing and validation

Names are normalized to lowercase before checks and storage.
Allowed characters are a-z, 0-9, and hyphen.
Subdomain format supports one dot only, in label.project form.
Dot cannot be first or last character.
Invalid names revert during registration.

Pricing behavior

Base price is length-based in USD tiers.
Oracle conversion is used for on-chain payment amount.
NFT holder discount is applied in contract logic when eligible.
Coupon discounts can apply when valid and active.
Project subdomain namespaces can define custom pricing tables.

Project subdomains and revenue split

ANS supports project subdomain namespaces such as label.project. Projects can request their own namespace and let their community register subdomains under that namespace.

How project subdomains work

Namespace must be enabled before registrations are allowed.
Registration format is exactly one dot: label.project.
Pricing can follow global tiers or a project-specific table.
Registered subdomains are standard ERC-721 assets.

Revenue model

Project share: 70% of revenue from registrations in its namespace.
Platform share: 30% of revenue for ANS infrastructure and operations.
Integrations should display this split clearly in partner-facing flows.
For namespace onboarding, coordinate with the ANS team.

Events to index

Indexing these events gives you reliable UI refresh and analytics pipelines.

DomainRegistered

Track new names, owners, token IDs, and price paid.

RecordSet

Refresh resolve state and display current record value.

TextRecordSet

Refresh profile text data like social links and avatar URLs.

DomainTransferred

Keep owner dashboards and ownership caches correct.

DomainMigrated

Label migrated names and update legacy mapping state.

Transfer

Standard ERC-721 transfer compatibility for generic indexers.

Error handling checklist

Map contract reverts to readable user messages.
Show explicit handling for insufficient payment states.
Explain name validation failures before write attempts.
Provide retry paths for stale or delayed price feed updates.
Use preflight reads to reduce failed writes.

Production launch checklist

Verify contract addresses and chain ID in all environments.
Test resolve and reverse lookup after transfer scenarios.
Test registerWithPriceUpdate and registerWithCouponAndPriceUpdate paths.
Test subdomain names and namespace-disabled failure states.
Set monitoring on key events and failed transaction rates.

Security and trust model

Always prioritize on-chain reads for critical state. Keep off-chain indexing as a speed layer, not as authoritative truth.

For high-risk actions, re-check ownership and price right before write execution.

If any translation is incorrect or needs changes, please join our Discord / Telegram.

Docs content version: v1.0.9