Get Renewal Price

Get the renewal price for an existing subname, including expiration status.

Endpoint

GET /api/subnames/{parent}/{name}/renewal-price

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 (e.g., alice)

Response

{
  "success": true,
  "name": "alice.aboutme.eth",
  "owner": "0x701B4937e6c943789ffA74CC8601813b2D87B454",
  "currentExpiry": "2025-02-09T18:30:00.000Z",
  "daysUntilExpiry": 365,
  "isExpired": false,
  "isExpiringSoon": false,
  "renewalPrice": 0.97,
  "tier": "standard",
  "currency": "USD",
  "extensionYears": 1
}

Response Fields

Field	Type	Description
name	string	Full subname
owner	string	Current owner address
currentExpiry	string	Current expiration timestamp
daysUntilExpiry	integer	Days until expiration (negative if expired)
isExpired	boolean	True if already expired
isExpiringSoon	boolean	True if expiring within 30 days
renewalPrice	number	Price in USD to renew for 1 year
tier	string	Pricing tier (determines price)
currency	string	Always "USD"
extensionYears	integer	Years added per renewal (always 1)

Expiration Status

Status	isExpired	isExpiringSoon	daysUntilExpiry
Active	false	false	> 30
Expiring Soon	false	true	1-30
Expired	true	false	≤ 0

Examples

cURL

curl "https://api.web3identity.com/api/subnames/aboutme.eth/alice/renewal-price"

JavaScript

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

// Check renewal status
const renewal = await getRenewalPrice('aboutme.eth', 'alice');

if (renewal.isExpired) {
  console.log('⚠️ Name has expired! Renew immediately to avoid losing it.');
} else if (renewal.isExpiringSoon) {
  console.log(`⏰ Expires in ${renewal.daysUntilExpiry} days. Consider renewing.`);
} else {
  console.log(`✅ Active until ${renewal.currentExpiry}`);
}

console.log(`Renewal price: $${renewal.renewalPrice}/year`);

Renewal Reminder System

async function checkRenewals(parent, names) {
  const results = await Promise.all(
    names.map(name => getRenewalPrice(parent, name))
  );
  
  const needsAttention = results.filter(r => r.isExpired || r.isExpiringSoon);
  
  if (needsAttention.length > 0) {
    console.log('Names needing renewal:');
    needsAttention.forEach(r => {
      const status = r.isExpired ? '❌ EXPIRED' : `⏰ ${r.daysUntilExpiry} days left`;
      console.log(`- ${r.name}: ${status} ($${r.renewalPrice})`);
    });
  }
  
  return needsAttention;
}

Error Responses

Status	Code	Description
404	NOT_FOUND	Subname does not exist
429	RATE_LIMITED	Rate limit exceeded
500	PRICE_ERROR	Internal server error

Related Endpoints

• Renew Subname — Perform the renewal (x402 payment)
• Get Price — Registration price for new names
• Get Details — Basic subname information