Renew Subname

Extend a subname registration by 1 year. Requires SIWE authentication and x402 payment.

Endpoint

POST /api/subnames/{parent}/{name}/renew

Authentication

SIWE + x402 Required

• Must be authenticated as the subname owner
• Payment required based on name tier pricing

Authorization: Bearer <jwt_token>
x-payment: <x402_payment_header>
payment-signature: <x402_payment_header>

Request Body

No body required (renewal is always for 1 year).

Response (Success)

{
  "success": true,
  "parent": "aboutme.eth",
  "name": "alice",
  "fullName": "alice.aboutme.eth",
  "owner": "0x701B4937e6c943789ffA74CC8601813b2D87B454",
  "previousExpiry": "2025-02-09T18:30:00.000Z",
  "newExpiry": "2026-02-09T18:30:00.000Z",
  "renewalPrice": 0.97,
  "tier": "standard",
  "note": "Renewal successful - extended by 1 year",
  "timestamp": "2024-02-10T14:30:00.000Z"
}

Response (402 - Payment Required)

When called without payment:

{
  "error": "Payment Required",
  "code": "PAYMENT_REQUIRED",
  "message": "Renewal requires $0.97 USDC",
  "renewalPrice": 0.97,
  "tier": "standard",
  "x402": {
    "accepts": [{
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0xF499102c8707c6501CaAdD2028c6DF1c6C6E813b",
      "amount": "970000",
      "maxTimeoutSeconds": 300
    }]
  }
}

Examples

cURL

# Authenticate first
TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Initial request (will return 402)
curl -X POST "https://api.web3identity.com/api/subnames/aboutme.eth/alice/renew" \
  -H "Authorization: Bearer $TOKEN"

# With payment (after making USDC payment)
curl -X POST "https://api.web3identity.com/api/subnames/aboutme.eth/alice/renew" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-payment: $PAYMENT_HEADER" \
  -H "payment-signature: $PAYMENT_HEADER"

JavaScript

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

async function renewSubname(parent, name, siweToken, wallet) {
  const x402Client = createX402Client({
    network: 'base',
    signer: wallet
  });
  
  const response = await x402Client.fetch(
    `https://api.web3identity.com/api/subnames/${parent}/${name}/renew`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${siweToken}`
      }
    }
  );
  
  return response.json();
}

// Renew a subname
const result = await renewSubname(
  'aboutme.eth',
  'alice',
  siweToken,
  wallet
);

console.log(`Renewed until: ${result.newExpiry}`);
console.log(`Paid: $${result.renewalPrice}`);

Full Renewal Flow

async function renewWithFullAuth(parent, name, signer) {
  // 1. Authenticate with SIWE
  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();
  
  const signature = await signer.signMessage(message);
  
  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();
  
  // 2. Check renewal price
  const priceRes = await fetch(
    `https://api.web3identity.com/api/subnames/${parent}/${name}/renewal-price`
  );
  const priceData = await priceRes.json();
  
  console.log(`Current expiry: ${priceData.currentExpiry}`);
  console.log(`Renewal price: $${priceData.renewalPrice}`);
  
  // 3. Renew with x402 payment
  const x402Client = createX402Client({ network: 'base', signer });
  
  return x402Client.fetch(
    `https://api.web3identity.com/api/subnames/${parent}/${name}/renew`,
    {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${token}` }
    }
  ).then(r => r.json());
}

Renewal Pricing

Renewal price equals registration price for the name tier:

Tier	Renewal Price
Standard (5+ chars)	$0.97/year
Short (4 chars)	$4.97/year
Dictionary	$9.97/year
Ultra Short (3 chars)	$19.97/year
Premium (1-2 chars)	$97.00/year

Error Responses

Status	Code	Description
401	AUTH_REQUIRED	No SIWE token provided
401	INVALID_TOKEN	Token is invalid or expired
402	PAYMENT_REQUIRED	x402 payment needed
402	INSUFFICIENT_PAYMENT	Payment less than required
403	NOT_OWNER	You don't own this subname
404	NOT_FOUND	Subname does not exist
429	RATE_LIMITED	Rate limit exceeded
500	RENEWAL_ERROR	Internal server error

Related Endpoints

• Get Renewal Price — Check price and expiry
• SIWE Authentication — Get authentication token
• Get Details — View current registration