Skip to main content

Register Your First Subname

This tutorial walks you through registering an ENS subname like yourname.aboutme.eth using the Web3 Identity API.

Prerequisites​

  • An Ethereum wallet (MetaMask, Rainbow, etc.)
  • For paid registrations: USDC on Base network

Overview​

Step 1: Check Availability​

Before registering, verify the name is available:

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

Response:

{
  "available": true,
  "fullName": "yourname.aboutme.eth",
  "pricing": {
    "price": 0.97,
    "priceFormatted": "$0.97",
    "tier": "standard"
  }
}

JavaScript​

async function checkAvailability(name) {
  const response = await fetch(
    `https://api.web3identity.com/api/subnames/aboutme.eth/${name}/available`
  );
  const data = await response.json();
  
  if (data.available) {
    console.log(`âś… ${data.fullName} is available!`);
    console.log(`Price: ${data.pricing.priceFormatted}`);
    return true;
  } else {
    console.log(`❌ ${name} is already taken`);
    return false;
  }
}

await checkAvailability('yourname');

Step 2: Try Free Registration​

Your first registration is FREE (one per wallet, one per IP). Try the free tier first:

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

Success Response​

{
  "success": true,
  "fullName": "yourname.aboutme.eth",
  "owner": "0xYourWalletAddress",
  "freeTier": true,
  "note": "This was your free registration. Additional names require payment."
}

🎉 Congratulations! Your subname is registered!

Free Tier Exhausted (402)​

If you've already used your free registration:

{
  "error": true,
  "code": "FREE_TIER_EXHAUSTED",
  "message": "Wallet 0xYour...Address has already used its free registration",
  "pricing": {
    "price": 0.97,
    "priceFormatted": "$0.97",
    "tier": "standard"
  },
  "nextStep": "Use POST /api/subnames/aboutme.eth/purchase with x402 payment"
}

Continue to Step 3 for paid registration.

Step 3: Purchase with x402 Payment​

If free tier is exhausted, use x402 micropayment:

3a. Set Up x402 Client​

npm install @x402/client ethers
import { createX402Client } from '@x402/client';
import { ethers } from 'ethers';

// Connect your wallet
const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();

// Create x402 client
const x402Client = createX402Client({
  network: 'base',  // USDC payments on Base
  signer
});

3b. Make the Purchase​

async function purchaseSubname(name, owner) {
  const response = await x402Client.fetch(
    `https://api.web3identity.com/api/subnames/aboutme.eth/purchase`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ name, owner })
    }
  );
  
  return response.json();
}

const result = await purchaseSubname('yourname', await signer.getAddress());
console.log(`âś… Registered: ${result.fullName}`);
console.log(`Paid: ${result.pricing.priceFormatted}`);

Step 4: Add Records (Optional)​

Customize your profile by adding ENS text records:

Authenticate with SIWE​

import { SiweMessage } from 'siwe';

// 1. Get nonce
const nonceRes = await fetch(
  'https://api.web3identity.com/api/auth/nonce',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ address: await signer.getAddress() })
  }
);
const { nonce, message } = await nonceRes.json();

// 2. Sign the message
const signature = await signer.signMessage(message);

// 3. Verify and get JWT
const verifyRes = await fetch(
  'https://api.web3identity.com/api/auth/verify',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message, signature })
  }
);
const { token } = await verifyRes.json();

Update Records​

const updateRes = await fetch(
  'https://api.web3identity.com/api/subnames/aboutme.eth/yourname',
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      records: {
        description: 'Web3 enthusiast & developer',
        url: 'https://yoursite.com',
        'com.twitter': '@yourhandle',
        'com.github': 'yourgithub',
        avatar: 'https://yoursite.com/avatar.png'
      }
    })
  }
);

console.log('âś… Records updated!');

Step 5: Verify Your Subname​

Check via API​

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

Check via ENS​

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

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

// Resolve your subname
const address = await client.getEnsAddress({
  name: normalize('yourname.aboutme.eth'),
});

console.log(`Resolves to: ${address}`);

Visit Your Profile​

Open in browser: https://yourname.aboutme.eth.limo

Complete Example​

Here's the full registration flow in one script:

import { ethers } from 'ethers';
import { createX402Client } from '@x402/client';

async function registerSubname(desiredName) {
  // Connect wallet
  const provider = new ethers.BrowserProvider(window.ethereum);
  const signer = await provider.getSigner();
  const address = await signer.getAddress();
  
  // 1. Check availability
  const availRes = await fetch(
    `https://api.web3identity.com/api/subnames/aboutme.eth/${desiredName}/available`
  );
  const { available, pricing } = await availRes.json();
  
  if (!available) {
    throw new Error(`${desiredName} is already taken!`);
  }
  
  console.log(`${desiredName} is available! Price: ${pricing.priceFormatted}`);
  
  // 2. Try free registration
  const freeRes = await fetch(
    'https://api.web3identity.com/api/subnames/aboutme.eth',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ name: desiredName, owner: address })
    }
  );
  
  if (freeRes.ok) {
    const result = await freeRes.json();
    console.log(`🎉 Registered ${result.fullName} for FREE!`);
    return result;
  }
  
  // 3. Free tier exhausted - use x402
  if (freeRes.status === 402) {
    console.log('Free tier used. Making payment...');
    
    const x402Client = createX402Client({
      network: 'base',
      signer
    });
    
    const purchaseRes = await x402Client.fetch(
      'https://api.web3identity.com/api/subnames/aboutme.eth/purchase',
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ name: desiredName, owner: address })
      }
    );
    
    const result = await purchaseRes.json();
    console.log(`🎉 Registered ${result.fullName} for ${result.pricing.priceFormatted}!`);
    return result;
  }
  
  throw new Error('Registration failed');
}

// Run it!
await registerSubname('yourname');

Pricing Reference​

Name LengthPriceExamples
5+ characters$0.97alice, developer
4 characters$4.97code, hash
3 characters$19.97abc, xyz
1-2 characters$97.00a, xy
Dictionary words$9.97crypto, alpha
First One Free!

Your first registration is completely free — no wallet signature or payment needed!

Next Steps​

Troubleshooting​

"Name is already taken"​

Choose a different name or add numbers/variations.

"Free tier exhausted"​

Use the /purchase endpoint with x402 payment.

"Invalid address"​

Ensure address is valid Ethereum format (0x + 40 hex chars).

SIWE "Nonce expired"​

Nonces expire after 5 minutes. Get a fresh nonce and try again.

Need help? support@web3identity.com