GET /v1/ens/records

ENS: Records

Read all records for an ENS name and prepare unsigned transactions to update them. Supports ETH addresses, text records (avatar, Twitter, etc.), and IPFS content hashes.

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

Read Records

Retrieve all records for a registered ENS name from its resolver.

Endpoint

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

Parameters

Parameter Type Required Description
name string Yes ENS name (with or without .eth suffix)

Request

curl "https://api.robotdomainsearch.com/v1/ens/records?name=vitalik"

Response

{
  "name": "vitalik.eth",
  "node": "0xee6c4522aab0003e8d14cd40a6af439055fd2577951148c14b6cea9a53475835",
  "resolver": "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63",
  "addresses": {
    "ETH": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
  },
  "text": {
    "avatar": "eip155:1/erc1155:0xb32979...",
    "com.twitter": "VitalikButerin",
    "com.github": "vbuterin",
    "url": "https://vitalik.eth.limo",
    "description": "hullo"
  },
  "contenthash": "0xe3010170122029f..."
}

Response Fields

Field Type Description
name string Full ENS name with .eth suffix
node string EIP-137 namehash (hex)
resolver string Resolver contract address
addresses object Map of coin type → address (currently ETH only)
text object Map of text record key → value
contenthash string Content hash (hex, typically IPFS CID)

Supported Text Keys

The API reads these well-known text record keys:

Key Description
avatar Avatar image URL or NFT reference
description Profile description
display Display name
email Email address
url Website URL
com.twitter Twitter/X username
com.github GitHub username
com.discord Discord username
org.telegram Telegram username

Note: Only records that have been set are returned. Empty or unset records are omitted.

Prepare Record Update

Build an unsigned multicall transaction to update ENS records. The transaction is sent to the name’s resolver contract.

Endpoint

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

Request Body

Field Type Required Description
name string Yes ENS name (with or without .eth suffix)
owner string Yes Ethereum address of the name owner (for gas estimation)
addresses object No Map of coin type → address to set
text object No Map of text record key → value to set
contenthash string No Content hash to set (hex)
network string No Network (only "mainnet" supported)

At least one of addresses, text, or contenthash must be provided.

Request

curl -X POST "https://api.robotdomainsearch.com/v1/ens/records/prepare-update" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "myname",
    "owner": "0xYourWalletAddress",
    "addresses": {
      "ETH": "0xNewEthAddress"
    },
    "text": {
      "com.twitter": "myhandle",
      "avatar": "https://example.com/avatar.png",
      "url": "https://mysite.com"
    }
  }'

Response

{
  "name": "myname.eth",
  "resolver": "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63",
  "transaction": {
    "to": "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63",
    "data": "0xac9650d8...",
    "value": "0x0",
    "gas_estimate": 150000,
    "chain_id": 1
  },
  "changes": [
    {"type": "addr", "key": "ETH", "value": "0xNewEthAddress"},
    {"type": "text", "key": "com.twitter", "value": "myhandle"},
    {"type": "text", "key": "avatar", "value": "https://example.com/avatar.png"},
    {"type": "text", "key": "url", "value": "https://mysite.com"}
  ]
}

Response Fields

Field Type Description
name string Full ENS name
resolver string Resolver contract address the transaction targets
transaction object Unsigned Ethereum transaction
transaction.to string Resolver contract address
transaction.data string Encoded multicall data (hex)
transaction.value string Always "0x0" (no ETH needed)
transaction.gas_estimate integer Estimated gas limit (~150k)
transaction.chain_id integer Chain ID (1 = mainnet)
changes array List of record changes in the transaction
changes[].type string Change type: "addr", "text", or "contenthash"
changes[].key string Record key
changes[].value string New value

Only the name owner (or an authorized operator) can successfully execute the record update transaction on-chain.

Errors

Code Error Description
400 missing_parameter Required field missing (name, owner, or at least one change)
400 invalid_request Invalid JSON body
400 records_failed Failed to read records (invalid name, etc.)
400 prepare_update_failed Failed to prepare update (invalid address, unsupported coin type)
400 unsupported_network Only mainnet is supported
405 method_not_allowed Wrong HTTP method

Supported Coin Types

Currently only ETH is supported for address records. Other coin types (BTC, etc.) require chain-specific binary encoding per ENSIP-9 and may be added in a future release.

Code Examples

Read + Update Records

import requests

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

# Read current records
records = requests.get(f"{BASE}/v1/ens/records", params={"name": "myname"}).json()
print(f"Current ETH address: {records['addresses'].get('ETH', 'not set')}")
print(f"Current Twitter: {records['text'].get('com.twitter', 'not set')}")

# Prepare an update
update = requests.post(f"{BASE}/v1/ens/records/prepare-update",
    json={
        "name": "myname",
        "owner": "0xYourWalletAddress",
        "text": {
            "com.twitter": "newhandle",
            "description": "My ENS profile"
        }
    })
result = update.json()
print(f"Changes: {len(result['changes'])} records to update")

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

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

// Read current records
const records = await fetch(`${BASE}/v1/ens/records?name=myname`).then(r => r.json());
console.log("ETH:", records.addresses.ETH);
console.log("Twitter:", records.text["com.twitter"]);

// Prepare an update
const update = await fetch(`${BASE}/v1/ens/records/prepare-update`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "myname",
    owner: "0xYourWalletAddress",
    text: { "com.twitter": "newhandle", description: "My ENS profile" }
  })
}).then(r => r.json());

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

Notes

  • Resolver lookup: The API automatically looks up the name’s resolver from the ENS registry. It falls back to the default PublicResolver if the lookup fails.
  • Multicall batching: Multiple record changes are batched into a single multicall() transaction for gas efficiency.
  • Gas estimates include a 20% buffer over the estimated on-chain cost.
  • Record updates are free (no ETH value required) — you only pay for gas.
📄 Raw markdown: /docs/api/ens-records.md