Skip to main content

Subnames API

ENS subnames provide hierarchical identity within the ENS namespace. Think of them like subdomains for the decentralized web — alice.aboutme.eth gives Alice a verifiable identity under the AboutMe.eth namespace.

Overview​

The Subnames API enables:

  • Registration — Create new subnames under supported parent names
  • Management — Update records, transfer ownership, renew registration
  • Resolution — Resolve subnames via CCIP-Read gateway (ERC-3668)

Supported Parent Names​

ParentStatusRegistration
aboutme.eth✅ PublicOpen to all (1 free per address)
atv.eth🔒 PrivateAdmin-only

Pricing (aboutme.eth)​

TierPrice/YearCriteria
Free$0.00First registration per wallet/IP
Standard$0.975+ characters
Short$4.974 characters
Dictionary$9.97Common English words
Ultra Short$19.973 characters
Premium$97.001-2 characters
First One Free!

Every wallet gets one free registration. No payment required!

Authentication Requirements​

Endpoint TypeAuth RequiredMethod
Read operations❌ NonePublic
Free registration❌ NoneOne per wallet/IP
Paid registration💳 x402USDC on Base
Update records🔐 SIWEMust own subname
Renew🔐 SIWE + 💳 x402Must own + payment
Transfer🔐 SIWEMust own subname
Delete🔐 SIWEMust own subname

All Endpoints​

Read Operations (Public)​

MethodEndpointDescription
GET/api/subnames/{parent}List subnames under parent
GET/api/subnames/{parent}/by-owner/{address}List names owned by address
GET/api/subnames/{parent}/allList all with full details
GET/api/subnames/{parent}/statsGlobal statistics
GET/api/subnames/{parent}/searchSearch by name or owner
GET/api/subnames/{parent}/{name}/availableCheck availability + pricing
GET/api/subnames/{parent}/{name}/profileFull profile with records
GET/api/subnames/{parent}/{name}Basic subname details
GET/api/subnames/{parent}/{name}/priceGet registration price
GET/api/subnames/{parent}/{name}/renewal-priceGet renewal quote

Write Operations (Auth Required)​

MethodEndpointAuthDescription
POST/api/subnames/{parent}Free tierRegister (free tier)
POST/api/subnames/{parent}/purchasex402Register with payment
PUT/api/subnames/{parent}/{name}SIWEUpdate records
POST/api/subnames/{parent}/{name}/renewSIWE + x402Renew registration
POST/api/subnames/{parent}/{name}/transferSIWETransfer ownership
DELETE/api/subnames/{parent}/{name}SIWEDelete subname

Quick Start​

Check Availability​

curl "https://api.web3identity.com/api/subnames/aboutme.eth/alice/available"

Register (Free)​

curl -X POST "https://api.web3identity.com/api/subnames/aboutme.eth" \
  -H "Content-Type: application/json" \
  -d '{"name":"alice","owner":"0xYourAddress"}'

View Profile​

curl "https://api.web3identity.com/api/subnames/aboutme.eth/alice/profile"

Resolution (CCIP-Read)​

Subnames resolve via our CCIP-Read gateway (ERC-3668):

import { createPublicClient, http } from 'viem';
import { mainnet } from 'viem/chains';
import { normalize } from 'viem/ens';

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
});

const address = await client.getEnsAddress({
  name: normalize('alice.aboutme.eth'),
});
console.log(address); // 0x123...

See CCIP Gateway for technical details.

Rate Limits​

TierDaily Limit
Anonymous100 requests
SIWE200 requests
API Key250 requests
x402Unlimited (pay-per-call)

Use Cases​

For Individuals:

  • Personal identity hub (link socials, avatar, bio)
  • Professional portfolio (developers, creators)
  • Event attendees (claim badge subnames)

For Agents:

  • Autonomous agent identity (agents can register & pay with x402)
  • Verifiable on-chain presence
  • Machine-readable records

For Communities:

  • Member badges (dao.project.eth)
  • Role-based access (mod.community.eth)
  • Event participation tracking

Web Interface​

Need help? support@web3identity.com