POST /v1/ens/register/check

ENS: Registration

Register ENS (.eth) names using the two-step commit/reveal flow. The API returns unsigned transactions that your wallet or backend signs and broadcasts.

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

Registration Flow

ENS uses a commit/reveal scheme to prevent front-running:

┌─────────────────────────────────────────────────────────────────────┐
│                   ENS Commit/Reveal Registration                    │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  1. POST /register/check          Check availability + pricing      │
│           │                                                         │
│           ▼                                                         │
│  2. POST /register/prepare-commit  Get unsigned commit tx + secret  │
│           │                                                         │
│           ▼                                                         │
│  3. Sign & broadcast commit tx     (your wallet)                    │
│           │                                                         │
│           ▼                                                         │
│  4. GET /tx/status?hash=0x...      Poll until confirmed             │
│           │                                                         │
│           ▼                                                         │
│  5. ⏳ Wait 60+ seconds            (min commitment age)             │
│           │                                                         │
│           ▼                                                         │
│  6. POST /register/prepare-register  Get unsigned register tx       │
│           │                                                         │
│           ▼                                                         │
│  7. Sign & broadcast register tx   (your wallet, sends ETH)        │
│           │                                                         │
│           ▼                                                         │
│  8. GET /tx/status?hash=0x...      Poll until confirmed             │
│           │                                                         │
│           ▼                                                         │
│  ✅ Name registered!                                                │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Important: There is a required wait of 60 seconds (minimum) between the commit transaction confirming and submitting the register transaction. The commitment expires after 24 hours.

Step 1: Check Registration

Check if an ENS name is available and get pricing, gas estimates, and commit timing.

Endpoint

POST https://api.robotdomainsearch.com/v1/ens/register/check

Request Body

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

Request

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

Response

{
  "name": "myname.eth",
  "available": true,
  "rent_price": {
    "base_wei": "158548959918",
    "premium_wei": "0",
    "total_wei": "158548959918",
    "total_eth": "0.000000158548959918",
    "usd_estimate": 5.00
  },
  "gas_estimate": {
    "commit_gas": 60000,
    "register_gas": 350000,
    "gas_price_wei": "30000000000"
  },
  "commit_wait": {
    "min_seconds": 60,
    "max_seconds": 86400
  }
}

Response Fields

Field	Type	Description
`name`	string	Full ENS name with `.eth` suffix
`available`	boolean	Whether the name is available
`rent_price`	object	On-chain rent price (only if available)
`rent_price.base_wei`	string	Base rent cost in wei
`rent_price.premium_wei`	string	Premium cost in wei (temporary premium for recently expired names)
`rent_price.total_wei`	string	Total cost in wei (base + premium)
`rent_price.total_eth`	string	Total cost in ETH
`rent_price.usd_estimate`	number	Estimated cost in USD
`gas_estimate`	object	Gas estimates for both transactions
`gas_estimate.commit_gas`	integer	Estimated gas for the commit transaction (~60k)
`gas_estimate.register_gas`	integer	Estimated gas for the register transaction (~350k)
`gas_estimate.gas_price_wei`	string	Current gas price in wei
`commit_wait`	object	Timing requirements for the commit/reveal window
`commit_wait.min_seconds`	integer	Minimum wait after commit (60 seconds on mainnet)
`commit_wait.max_seconds`	integer	Maximum wait before commitment expires (86400 seconds / 24 hours)

Response (Name Unavailable)

If the name is already registered, only name and available are returned:

{
  "name": "vitalik.eth",
  "available": false
}

Step 2: Prepare Commit Transaction

Generate a random secret, compute the commitment hash, and get an unsigned commit transaction.

Endpoint

POST https://api.robotdomainsearch.com/v1/ens/register/prepare-commit

Request Body

Field	Type	Required	Description
`name`	string	Yes	ENS name (without `.eth` suffix)
`owner`	string	Yes	Ethereum address that will own the name
`duration_years`	integer	No	Registration duration in years (default: 1)
`set_reverse_record`	boolean	No	Set reverse record for the owner address (default: `true`)
`network`	string	No	Network (only `"mainnet"` supported)

Request

curl -X POST "https://api.robotdomainsearch.com/v1/ens/register/prepare-commit" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "myname",
    "owner": "0xYourWalletAddress",
    "duration_years": 1
  }'

Response

{
  "registration_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "name": "myname.eth",
  "secret": "0x7f3a...random32bytes...9c2e",
  "commitment": "0x8d4f...commitmenthash...1a3b",
  "transaction": {
    "to": "0x253553366Da8546fC250F225fe3d25d0C782303b",
    "data": "0xf14fcbc8...",
    "value": "0x0",
    "gas_estimate": 60000,
    "chain_id": 1
  },
  "min_wait_seconds": 60,
  "max_wait_seconds": 86400
}

Response Fields

Field	Type	Description
`registration_id`	string	Unique ID for this registration (used in Step 3)
`name`	string	Full ENS name
`secret`	string	Random 32-byte secret (hex) — save this
`commitment`	string	Commitment hash (hex)
`transaction`	object	Unsigned Ethereum transaction to sign and broadcast
`transaction.to`	string	ENS Controller contract address
`transaction.data`	string	Encoded calldata for the `commit()` function
`transaction.value`	string	ETH value (always `"0x0"` for commit)
`transaction.gas_estimate`	integer	Estimated gas limit
`transaction.chain_id`	integer	Chain ID (1 = Ethereum mainnet)
`min_wait_seconds`	integer	Minimum seconds to wait after commit confirms
`max_wait_seconds`	integer	Maximum seconds before commitment expires

Save the registration_id — you’ll need it for Step 3 (prepare-register).

After receiving the response:

Sign the transaction with the owner’s wallet
Broadcast the signed transaction to the network
Poll /v1/ens/tx/status until the commit is confirmed
Wait at least min_wait_seconds (60 seconds on mainnet)

Step 3: Prepare Register Transaction

After the commit transaction is confirmed and the wait period has passed, prepare the register transaction.

Endpoint

POST https://api.robotdomainsearch.com/v1/ens/register/prepare-register

Request Body

Field	Type	Required	Description
`registration_id`	string	Yes	Registration ID from Step 2
`network`	string	No	Network (only `"mainnet"` supported)

Request

curl -X POST "https://api.robotdomainsearch.com/v1/ens/register/prepare-register" \
  -H "Content-Type: application/json" \
  -d '{"registration_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"}'

Response

{
  "registration_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "name": "myname.eth",
  "transaction": {
    "to": "0x253553366Da8546fC250F225fe3d25d0C782303b",
    "data": "0x74694a2b...",
    "value": "0x24f52b97c6",
    "gas_estimate": 350000,
    "chain_id": 1
  },
  "rent_price": {
    "base_wei": "158548959918",
    "premium_wei": "0",
    "total_wei": "158548959918",
    "total_eth": "0.000000158548959918"
  },
  "value_with_buffer": "174403855910"
}

Response Fields

Field	Type	Description
`registration_id`	string	Registration ID
`name`	string	Full ENS name
`transaction`	object	Unsigned Ethereum transaction to sign and broadcast
`transaction.to`	string	ENS Controller contract address
`transaction.data`	string	Encoded calldata for the `register()` function
`transaction.value`	string	ETH value to send (hex) — includes 10% buffer
`transaction.gas_estimate`	integer	Estimated gas limit
`transaction.chain_id`	integer	Chain ID
`rent_price`	object	Current on-chain rent price
`value_with_buffer`	string	Total value in wei (rent + 10% buffer for price fluctuation)

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

Errors

All error responses follow the standard format:

{
  "error": "error_code",
  "message": "Human-readable description"
}

Code	Error	Description
400	`missing_parameter`	Required field is missing
400	`invalid_request`	Invalid JSON body
400	`unsupported_network`	Only `mainnet` is supported
400	`check_failed`	Ethereum RPC error during check
400	`prepare_commit_failed`	Failed to prepare commit (invalid address, etc.)
405	`method_not_allowed`	Wrong HTTP method (all registration endpoints use POST)
500	`prepare_register_failed`	Failed to prepare register (expired registration, not found)

Common Failure Modes

Registration expired: The registration_id is valid for 24 hours. After that, you must start over from Step 2.
Invalid owner address: Must be a valid Ethereum hex address (0x + 40 hex chars).
Name too short: ENS names must be at least 3 characters.
Name unavailable: Cannot register a name that’s already taken.
Commitment not matured: Wait at least 60 seconds between commit confirmation and register.

End-to-End Example

Python

import requests
import time

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

# Step 1: Check availability
check = requests.post(f"{BASE}/v1/ens/register/check",
    json={"name": "myname", "duration_years": 1})
data = check.json()

if not data["available"]:
    print(f"{data['name']} is not available")
    exit()

print(f"{data['name']} available — {data['rent_price']['total_eth']} ETH/year")

# Step 2: Prepare commit
commit = requests.post(f"{BASE}/v1/ens/register/prepare-commit",
    json={
        "name": "myname",
        "owner": "0xYourWalletAddress",
        "duration_years": 1
    })
commit_data = commit.json()
reg_id = commit_data["registration_id"]

# --> Sign and broadcast commit_data["transaction"] with your wallet
# --> Poll /tx/status until confirmed

# Wait for commitment to mature (60+ seconds)
print("Waiting 70 seconds for commitment to mature...")
time.sleep(70)

# Step 3: Prepare register
register = requests.post(f"{BASE}/v1/ens/register/prepare-register",
    json={"registration_id": reg_id})
register_data = register.json()

# --> Sign and broadcast register_data["transaction"] with your wallet
# --> The transaction.value contains ETH to send (with 10% buffer)
# --> Poll /tx/status until confirmed

print(f"Registration complete! {register_data['name']} is yours.")

JavaScript

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

// Step 1: Check availability
const check = await fetch(`${BASE}/v1/ens/register/check`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "myname", duration_years: 1 })
});
const checkData = await check.json();

if (!checkData.available) {
  console.log(`${checkData.name} is not available`);
  process.exit(1);
}

console.log(`${checkData.name} — ${checkData.rent_price.total_eth} ETH/year`);

// Step 2: Prepare commit
const commit = await fetch(`${BASE}/v1/ens/register/prepare-commit`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "myname",
    owner: "0xYourWalletAddress",
    duration_years: 1
  })
});
const commitData = await commit.json();

// --> Sign and broadcast commitData.transaction with ethers.js or viem
// --> Poll /tx/status until confirmed
// --> Wait 60+ seconds

// Step 3: Prepare register
const register = await fetch(`${BASE}/v1/ens/register/prepare-register`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ registration_id: commitData.registration_id })
});
const registerData = await register.json();

// --> Sign and broadcast registerData.transaction (includes ETH value)
// --> Poll /tx/status until confirmed

Notes

Mainnet only: Phase 1 supports Ethereum mainnet only.
Unsigned transactions: The API returns unsigned transactions. You must sign and broadcast them with your own wallet (ethers.js, viem, MetaMask, etc.).
ETH required: The register transaction requires sending ETH (the rent price + 10% buffer). Excess is refunded by the contract.
Reverse record: By default, the API sets a reverse record so the owner address resolves back to the ENS name. Pass "set_reverse_record": false to disable.
Gas estimates include a 20% buffer over the estimated on-chain cost for safety.
Registration state expires after 24 hours. If you don’t complete the register step in time, start over from prepare-commit.

ENS: Check Availability — quick availability + pricing check
ENS: Transaction Status — poll transaction status
ENS: Records — read and update ENS records
ENS: Renewal — renew existing names

📄 Raw markdown: /docs/api/ens-registration.md

ENS: Registration

Registration Flow

Step 1: Check Registration

Endpoint

Request Body

Request

Response

Response Fields

Response (Name Unavailable)

Step 2: Prepare Commit Transaction

Endpoint

Request Body

Request

Response

Response Fields

Step 3: Prepare Register Transaction

Endpoint

Request Body

Request

Response

Response Fields

Errors

Common Failure Modes

End-to-End Example

Python

JavaScript

Notes

Related