Skip to main content

Text Records

Read ENS text records including social handles, URLs, email, and custom fields.

Endpoints​

EndpointDescriptionPrice
GET /api/ens/{name}/recordsAll text records$0.01
GET /api/ens/{name}/record/{key}Single record$0.001
GET /api/records/batchMultiple names/keys$0.02
GET /api/records/searchSearch by record value$0.02

GET /api/ens/{name}/records​

Get all text records for an ENS name.

Request​

curl https://api.web3identity.com/api/ens/records/vitalik.eth

Response​

{
  "name": "vitalik.eth",
  "records": {
    "avatar": "eip155:1/erc721:0xb7f7f6c52f2e2fdb1963eab30438024864c313f6/2430",
    "description": "ethereum.org",
    "url": "https://vitalik.eth.limo",
    "com.twitter": "VitalikButerin",
    "com.github": "vbuterin",
    "email": null,
    "com.discord": null,
    "org.telegram": null,
    "notice": null,
    "keywords": null,
    "location": null
  },
  "resolver": "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63",
  "recordCount": 5
}

SDK​

const records = await client.getTextRecords('vitalik.eth');
console.log(records['com.twitter']); // "VitalikButerin"

GET /api/ens/{name}/record/{key}​

Get a single text record by key.

Request​

curl https://api.web3identity.com/api/ens/record/vitalik.eth/com.twitter

Response​

{
  "name": "vitalik.eth",
  "key": "com.twitter",
  "value": "VitalikButerin",
  "normalized": {
    "platform": "twitter",
    "handle": "VitalikButerin",
    "url": "https://twitter.com/VitalikButerin"
  }
}

SDK​

const twitter = await client.getTextRecord('vitalik.eth', 'com.twitter');

Standard Record Keys​

Social Platforms​

KeyDescriptionExample Value
com.twitterTwitter/X handleVitalikButerin
com.githubGitHub usernamevbuterin
com.discordDiscord usernamevitalik#1234
org.telegramTelegram usernamevitalik
com.linkedinLinkedIn pathin/vitalik
io.farcasterFarcaster usernamevitalik
com.youtubeYouTube channel@vitalik
app.lensLens Protocol handlevitalik.lens

Profile Information​

KeyDescriptionExample Value
avatarProfile pictureipfs://Qm... or NFT URI
descriptionBio/descriptionBuilding Ethereum
urlWebsite URLhttps://vitalik.eth.limo
emailEmail addresshello@vitalik.eth
locationLocationSingapore
keywordsComma-separated tagsethereum,web3,crypto
noticePublic noticeDMs open

Web3 Records​

KeyDescriptionExample Value
contenthashIPFS/IPNS/Swarm hashipfs://Qm...
eth.addrETH address0xd8dA...
btc.addrBitcoin addressbc1q...
sol.addrSolana addressHqmf...

GET /api/records/batch​

Query multiple records across multiple names.

Request​

curl -X POST https://api.web3identity.com/api/records/batch \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      { "name": "vitalik.eth", "keys": ["com.twitter", "com.github"] },
      { "name": "nick.eth", "keys": ["com.twitter"] }
    ]
  }'

Response​

{
  "results": {
    "vitalik.eth": {
      "com.twitter": "VitalikButerin",
      "com.github": "vbuterin"
    },
    "nick.eth": {
      "com.twitter": "nicksdjohnson"
    }
  },
  "count": 2
}

SDK​

const records = await client.batchRecords([
  { name: 'vitalik.eth', keys: ['com.twitter', 'com.github'] },
  { name: 'nick.eth', keys: ['com.twitter'] }
]);

GET /api/records/search​

Find ENS names by record value.

Request​

# Find all names with a specific Twitter handle
curl "https://api.web3identity.com/api/records/search?key=com.twitter&value=VitalikButerin"

Response​

{
  "query": {
    "key": "com.twitter",
    "value": "VitalikButerin"
  },
  "results": [
    {
      "name": "vitalik.eth",
      "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
    }
  ],
  "count": 1
}

Use Cases​

  • Verify Twitter handle ownership
  • Find ENS name for GitHub user
  • Discover connected identities

Custom Records​

ENS supports arbitrary custom records:

# Query custom record
curl https://api.web3identity.com/api/ens/example.eth/record/com.myapp.userId

Common patterns:

  • com.{domain}.{key} — App-specific data
  • io.{protocol}.{key} — Protocol-specific data
  • xyz.{key} — Generic namespace

Cointype Addresses​

Query multi-chain addresses:

# Bitcoin address
curl https://api.web3identity.com/api/ens/record/vitalik.eth/addr.60  # ETH (cointype 60)
curl https://api.web3identity.com/api/ens/record/vitalik.eth/addr.0   # BTC (cointype 0)
curl https://api.web3identity.com/api/ens/record/vitalik.eth/addr.501 # SOL (cointype 501)

GET /api/ens/{name}/addresses​

Get all multi-chain addresses:

curl https://api.web3identity.com/api/ens/addresses/vitalik.eth
{
  "name": "vitalik.eth",
  "addresses": {
    "eth": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "btc": null,
    "sol": null,
    "ltc": null
  }
}

Errors​

CodeHTTPDescription
NAME_NOT_FOUND404ENS name not registered
NO_RESOLVER404No resolver set for name
RECORD_NOT_SET404Specific record not set
INVALID_KEY400Invalid record key format

Example Error​

{
  "error": true,
  "code": "RECORD_NOT_SET",
  "message": "Record 'com.twitter' is not set for 'example.eth'"
}