Check Availability

Check if a subname is available for registration and get pricing information.

Endpoint

GET /api/subnames/{parent}/{name}/available

Authentication

None required — This is a public read endpoint.

Parameters

Parameter	Type	Location	Required	Description
parent	string	path	✅	Parent ENS name (e.g., aboutme.eth)
name	string	path	✅	Subname label to check (e.g., alice)

Response (Available)

{
  "parent": "aboutme.eth",
  "name": "alice",
  "fullName": "alice.aboutme.eth",
  "available": true,
  "pricing": {
    "price": 0.97,
    "priceFormatted": "$0.97",
    "tier": "standard",
    "reason": "Standard name"
  },
  "timestamp": "2024-02-10T14:30:00.000Z"
}

Response (Taken)

{
  "parent": "aboutme.eth",
  "name": "vitalik",
  "fullName": "vitalik.aboutme.eth",
  "available": false,
  "pricing": {
    "price": 9.97,
    "priceFormatted": "$9.97",
    "tier": "dictionary",
    "reason": "Dictionary word"
  },
  "timestamp": "2024-02-10T14:30:00.000Z"
}

Pricing Tiers

Tier	Price/Year	Criteria
ultraPremium	$97.00	1-2 characters
ultraShort	$19.97	3 characters
dictionary	$9.97	Common English words
short	$4.97	4 characters
standard	$0.97	5+ characters
reserved	N/A	Reserved names (not available)

Free Registration

First registration per wallet/IP is FREE! Additional registrations require payment.

Examples

cURL

# Check if "mycoolname" is available
curl "https://api.web3identity.com/api/subnames/aboutme.eth/mycoolname/available"

# Check a 3-character name
curl "https://api.web3identity.com/api/subnames/aboutme.eth/abc/available"

JavaScript

async function checkAvailability(parent, name) {
  const response = await fetch(
    `https://api.web3identity.com/api/subnames/${parent}/${name}/available`
  );
  return response.json();
}

// Check availability before registration
const result = await checkAvailability('aboutme.eth', 'mycoolname');

if (result.available) {
  console.log(`${result.fullName} is available!`);
  console.log(`Price: ${result.pricing.priceFormatted}/year (${result.pricing.tier})`);
} else {
  console.log(`${result.fullName} is already taken`);
}

React Hook Example

import { useState, useEffect } from 'react';

function useSubnameAvailability(parent, name) {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(false);
  
  useEffect(() => {
    if (!name || name.length < 1) return;
    
    setLoading(true);
    fetch(`https://api.web3identity.com/api/subnames/${parent}/${name}/available`)
      .then(res => res.json())
      .then(setData)
      .finally(() => setLoading(false));
  }, [parent, name]);
  
  return { data, loading };
}

// Usage
function RegistrationForm() {
  const [name, setName] = useState('');
  const { data, loading } = useSubnameAvailability('aboutme.eth', name);
  
  return (
    <div>
      <input 
        value={name} 
        onChange={e => setName(e.target.value)}
        placeholder="Enter desired name"
      />
      {loading && <span>Checking...</span>}
      {data?.available && <span className="available">✓ Available - {data.pricing.priceFormatted}</span>}
      {data && !data.available && <span className="taken">✗ Already taken</span>}
    </div>
  );
}

Reserved Names

Some names are reserved and cannot be registered:

• admin, support, help
• official, verified
• aboutme, register, api

These return available: false with tier: "reserved".

Error Responses

Status	Code	Description
400	BAD_REQUEST	Invalid name format
429	RATE_LIMITED	Rate limit exceeded
500	SUBNAME_ERROR	Internal server error

Related Endpoints

• Get Price — Get pricing only
• Register — Register a subname (free tier)
• Purchase — Purchase with x402 payment