GET /v1/ens/expiry

ENS: Renewal

Check when an ENS name expires and prepare unsigned renewal transactions. Anyone can renew any ENS name — no ownership required.

Base URL: https://api.robotdomainsearch.com — ENS endpoints are proxied through the main API at /v1/ens/*.

Check Expiry

Look up when an ENS name expires, whether it’s in the grace period, and what renewal costs.

Endpoint

GET https://api.robotdomainsearch.com/v1/ens/expiry

Parameters

Parameter Type Required Description
name string Yes ENS name (with or without .eth suffix)
duration_years integer No Renewal duration for cost estimate (default: 1)

Request

curl "https://api.robotdomainsearch.com/v1/ens/expiry?name=vitalik&duration_years=2"

Response

{
  "name": "vitalik.eth",
  "expires_at": "2032-05-04T10:00:00Z",
  "expires_at_unix": 1967104800,
  "grace_period_ends": "2032-08-02T10:00:00Z",
  "is_expired": false,
  "in_grace_period": false,
  "renewal_cost": {
    "base_wei": "317097919836",
    "premium_wei": "0",
    "total_wei": "317097919836",
    "total_eth": "0.000000317097919836",
    "usd_estimate": 10.00
  }
}

Response Fields

Field Type Description
name string Full ENS name
expires_at string Expiry date (ISO 8601)
expires_at_unix integer Expiry timestamp (Unix seconds)
grace_period_ends string End of 90-day grace period (ISO 8601)
is_expired boolean Whether the name has passed its expiry date
in_grace_period boolean Whether the name is in the 90-day grace period
renewal_cost object Renewal cost for the requested duration
renewal_cost.base_wei string Base renewal cost in wei
renewal_cost.premium_wei string Premium in wei (may be non-zero for recently expired names)
renewal_cost.total_wei string Total cost in wei
renewal_cost.total_eth string Total cost in ETH
renewal_cost.usd_estimate number Estimated cost in USD

Grace Period

After an ENS name expires, there is a 90-day grace period during which:

  • The original owner can still renew (at normal price)
  • The name cannot be re-registered by someone else
  • After the grace period ends, a temporary premium is applied that decays over ~21 days

Prepare Renewal

Build an unsigned renewal transaction.

Endpoint

POST https://api.robotdomainsearch.com/v1/ens/renew/prepare

Request Body

Field Type Required Description
name string Yes ENS name (with or without .eth suffix)
duration_years integer No Renewal duration in years (default: 1)
network string No Network (only "mainnet" supported)

Request

curl -X POST "https://api.robotdomainsearch.com/v1/ens/renew/prepare" \
  -H "Content-Type: application/json" \
  -d '{"name": "myname", "duration_years": 2}'

Response

{
  "name": "myname.eth",
  "transaction": {
    "to": "0x253553366Da8546fC250F225fe3d25d0C782303b",
    "data": "0xacf1a841...",
    "value": "0x49d7c0e8c5",
    "gas_estimate": 120000,
    "chain_id": 1
  },
  "rent_price": {
    "base_wei": "317097919836",
    "premium_wei": "0",
    "total_wei": "317097919836",
    "total_eth": "0.000000317097919836",
    "usd_estimate": 10.00
  },
  "value_with_buffer": "348807711820",
  "new_expiry": "2028-03-27T12:00:00Z"
}

Response Fields

Field Type Description
name string Full ENS name
transaction object Unsigned Ethereum transaction
transaction.to string ENS Controller contract address
transaction.data string Encoded calldata for renew() function
transaction.value string ETH to send (hex) — includes 10% buffer
transaction.gas_estimate integer Estimated gas limit (~120k)
transaction.chain_id integer Chain ID (1 = mainnet)
rent_price object Current on-chain renewal price
value_with_buffer string Total value in wei (rent + 10% buffer)
new_expiry string Projected new expiry date after renewal (ISO 8601)

The transaction.value includes a 10% buffer to account for ETH price fluctuations. The ENS contract refunds any excess.

Anyone can renew any name. Unlike registration, renewal doesn’t require ownership — this is by design in the ENS protocol.

Errors

Code Error Description
400 missing_parameter name is required
400 invalid_request Invalid JSON body
400 unsupported_network Only mainnet is supported
400 expiry_failed Failed to look up expiry (name not registered, etc.)
400 prepare_renew_failed Failed to prepare renewal transaction
405 method_not_allowed Wrong HTTP method

Code Examples

Check Expiry + Renew

import requests
from datetime import datetime

BASE = "https://api.robotdomainsearch.com"

# Check expiry
expiry = requests.get(f"{BASE}/v1/ens/expiry",
    params={"name": "myname", "duration_years": 1}).json()

expires = datetime.fromisoformat(expiry["expires_at"].replace("Z", "+00:00"))
cost = expiry["renewal_cost"]["usd_estimate"]
print(f"{expiry['name']} expires {expires.strftime('%Y-%m-%d')} — ${cost} to renew")

if expiry["is_expired"] and not expiry["in_grace_period"]:
    print("Grace period has ended — name may be available for re-registration")
else:
    # Prepare renewal
    renew = requests.post(f"{BASE}/v1/ens/renew/prepare",
        json={"name": "myname", "duration_years": 1}).json()

    print(f"Renewal tx value: {renew['rent_price']['total_eth']} ETH")
    print(f"New expiry: {renew['new_expiry']}")

    # --> Sign and broadcast renew["transaction"] with your wallet

const BASE = "https://api.robotdomainsearch.com";

// Check expiry
const expiry = await fetch(
  `${BASE}/v1/ens/expiry?name=myname&duration_years=1`
).then(r => r.json());

console.log(`Expires: ${expiry.expires_at}`);
console.log(`Cost: ~$${expiry.renewal_cost.usd_estimate}/year`);

// Prepare renewal
const renew = await fetch(`${BASE}/v1/ens/renew/prepare`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "myname", duration_years: 1 })
}).then(r => r.json());

console.log(`New expiry: ${renew.new_expiry}`);

// --> Sign and broadcast renew.transaction with ethers.js or viem

Notes

  • Anyone can renew any name — the ENS protocol allows third-party renewals by design.
  • ETH required: The renewal transaction requires sending ETH. The 10% buffer accounts for price fluctuations; excess is refunded.
  • Gas estimates include a 20% buffer over the estimated on-chain cost.
  • Grace period: 90 days after expiry. During this window, the original owner can renew. After the grace period, a temporary premium applies.
📄 Raw markdown: /docs/api/ens-renewal.md