ENS Resolution

Most apps need ENS resolution in two directions:

Forward — given a name (vitalik.eth), load avatar, bio, links, and multichain addresses.
Reverse — given an address, find its primary name on a chain and render that identity.

Behind either direction sits the same protocol complexity: resolver contracts, coin-type encoding, inconsistent text-record keys, and avatar formats that may be URLs, IPFS paths, or NFT references. The Omnigraph handles that complexity for you and returns clean, structured results — forward, reverse, or chained reverse-and-forward — in one request.

Forward resolution — interpreted profile

When you have a name and need display-ready data, query domain.resolve.profile. This is where the Omnigraph does the heavy lifting: instead of decoding coin types, normalizing text-record keys, and chasing avatar formats yourself, you get a consumer-shaped view of the most common display fields — ready to drop into a UI or hand straight to an AI agent.

This query below loads a domain's high-level profile (avatar, socials, addresses, and more).

Run in ENSAdmin Open an interactive playground to execute this example on our alpha ENSNode instance.

GraphQL

query DomainProfile($name: InterpretedName!) {
  domain(by: {name: $name}) {
    resolve {
      profile {
        description
        avatar {
          httpUrl
        }
        addresses {
          ethereum
          base
          solana
          bitcoin
          rootstock
        }
        socials {
          github {
            handle
            httpUrl
          }
          twitter {
            handle
            httpUrl
          }
        }
        website {
          httpUrl
        }
        header {
          httpUrl
        }
      }
    }
  }
}

Variables

{
  "name": "gregskril.eth"
}

Output

{
  "data": {
    "domain": {
      "resolve": {
        "profile": {
          "description": "I like baking and building apps on web3 protocols.",
          "avatar": {
            "httpUrl": "https://gregskril.com/img/profile.jpg"
          },
          "addresses": {
            "ethereum": "0x179a862703a4adfb29896552df9e307980d19285",
            "base": "0x179a862703a4adfb29896552df9e307980d19285",
            "solana": "2JQANQn1kccapb7GT8XScf9qBy59uMo9vh9WwVQhwStJ",
            "bitcoin": "3NnpwUMGdGKuYaPDQagNXAgVXz9HdnJDNS",
            "rootstock": "0x179a862703A4AdFb29896552dF9e307980D19285"
          },
          "socials": {
            "github": {
              "handle": "gskril",
              "httpUrl": "https://github.com/gskril"
            },
            "twitter": {
              "handle": "gregskril",
              "httpUrl": "https://x.com/gregskril"
            }
          },
          "website": {
            "httpUrl": "https://gregskril.com/"
          },
          "header": {
            "httpUrl": "https://files.gregskril.com/cdn/QmfGaXqmqasCrKktBgD4AvvJb3DLndiKXdz457uBGLTFGK"
          }
        }
      }
    }
  }
}

Output matches a point in time snapshot GraphQL response from our alpha ENSNode instance. Live output depends on the configuration of your ENSNode instance and ENS state updates.

Opens an editable StackBlitz project with this snippet.

TypeScript

import { createEnsNodeClient } from "enssdk/core";
import { asInterpretedName } from "enssdk";
import { graphql, omnigraph } from "enssdk/omnigraph";

const client = createEnsNodeClient({
  url: process.env.ENSNODE_URL || "https://api.alpha.ensnode.io"
}).extend(omnigraph);

const DomainProfileQuery = graphql(`
  query DomainProfile($name: InterpretedName!) {
    domain(by: {name: $name}) {
      resolve {
        profile {
          description
          avatar {
            httpUrl
          }
          addresses {
            ethereum
            base
            solana
            bitcoin
            rootstock
          }
          socials {
            github {
              handle
              httpUrl
            }
            twitter {
              handle
              httpUrl
            }
          }
          website {
            httpUrl
          }
          header {
            httpUrl
          }
        }
      }
    }
  }
`);

const result = await client.omnigraph.query({
  query: DomainProfileQuery,
  variables:   {
    name: asInterpretedName("gregskril.eth"),
  },
});

if (result.errors) throw new Error(JSON.stringify(result.errors));
console.log(JSON.stringify(result.data, null, 2));

Output

{
  "data": {
    "domain": {
      "resolve": {
        "profile": {
          "description": "I like baking and building apps on web3 protocols.",
          "avatar": {
            "httpUrl": "https://gregskril.com/img/profile.jpg"
          },
          "addresses": {
            "ethereum": "0x179a862703a4adfb29896552df9e307980d19285",
            "base": "0x179a862703a4adfb29896552df9e307980d19285",
            "solana": "2JQANQn1kccapb7GT8XScf9qBy59uMo9vh9WwVQhwStJ",
            "bitcoin": "3NnpwUMGdGKuYaPDQagNXAgVXz9HdnJDNS",
            "rootstock": "0x179a862703A4AdFb29896552dF9e307980D19285"
          },
          "socials": {
            "github": {
              "handle": "gskril",
              "httpUrl": "https://github.com/gskril"
            },
            "twitter": {
              "handle": "gregskril",
              "httpUrl": "https://x.com/gregskril"
            }
          },
          "website": {
            "httpUrl": "https://gregskril.com/"
          },
          "header": {
            "httpUrl": "https://files.gregskril.com/cdn/QmfGaXqmqasCrKktBgD4AvvJb3DLndiKXdz457uBGLTFGK"
          }
        }
      }
    }
  }
}

Output matches a point in time snapshot GraphQL response from our alpha ENSNode instance. Live output depends on the configuration of your ENSNode instance and ENS state updates.

# 1. Create project
mkdir -p my-ens-script/src && cd my-ens-script
npm init -y && touch src/index.ts
npm pkg set type=module scripts.start="tsx src/index.ts"
# 2. Install dependencies
npm install enssdk@1.15.1 && npm install -D tsx typescript @types/node
# 3. Paste the TypeScript snippet above into src/index.ts
# 4. Run
ENSNODE_URL=https://api.alpha.ensnode.io npm start

# 1. Create project
mkdir -p my-ens-script/src && cd my-ens-script
pnpm init && touch src/index.ts
pnpm pkg set type=module scripts.start="tsx src/index.ts"
# 2. Install dependencies
pnpm add enssdk@1.15.1 && pnpm add -D tsx typescript @types/node
# 3. Paste the TypeScript snippet above into src/index.ts
# 4. Run
ENSNODE_URL=https://api.alpha.ensnode.io pnpm start

See the enssdk docs for gql.tada plugin and tsconfig setup.

Opens an editable StackBlitz project with this snippet.

TSX (React)

import { OmnigraphProvider, useOmnigraphQuery, graphql } from "enskit/react/omnigraph";
import { createEnsNodeClient } from "enssdk/core";
import { asInterpretedName } from "enssdk";
import { omnigraph } from "enssdk/omnigraph";

const client = createEnsNodeClient({
  url: import.meta.env.VITE_ENSNODE_URL || "https://api.alpha.ensnode.io"
}).extend(omnigraph);

const DomainProfileQuery = graphql(`
  query DomainProfile($name: InterpretedName!) {
    domain(by: {name: $name}) {
      resolve {
        profile {
          description
          avatar {
            httpUrl
          }
          addresses {
            ethereum
            base
            solana
            bitcoin
            rootstock
          }
          socials {
            github {
              handle
              httpUrl
            }
            twitter {
              handle
              httpUrl
            }
          }
          website {
            httpUrl
          }
          header {
            httpUrl
          }
        }
      }
    }
  }
`);

function DomainProfileResult() {
  const [result] = useOmnigraphQuery({
    query: DomainProfileQuery,
    variables:     {
      name: asInterpretedName("gregskril.eth"),
    },
  });
  const { data, fetching, error } = result;
  if (!data && fetching) return <p>Loading…</p>;
  if (error) return <p>Error: {error.message}</p>;
  if (!data) return <p>No data returned.</p>;
  const formatted = JSON.stringify(
    data,
    (_, value) => (typeof value === "bigint" ? value.toString() : value),
    2,
  );
  return <code>{formatted}</code>;
}

export default function App() {
  return (
    <OmnigraphProvider client={client}>
      <DomainProfileResult />
    </OmnigraphProvider>
  );
}

Output

{
  "data": {
    "domain": {
      "resolve": {
        "profile": {
          "description": "I like baking and building apps on web3 protocols.",
          "avatar": {
            "httpUrl": "https://gregskril.com/img/profile.jpg"
          },
          "addresses": {
            "ethereum": "0x179a862703a4adfb29896552df9e307980d19285",
            "base": "0x179a862703a4adfb29896552df9e307980d19285",
            "solana": "2JQANQn1kccapb7GT8XScf9qBy59uMo9vh9WwVQhwStJ",
            "bitcoin": "3NnpwUMGdGKuYaPDQagNXAgVXz9HdnJDNS",
            "rootstock": "0x179a862703A4AdFb29896552dF9e307980D19285"
          },
          "socials": {
            "github": {
              "handle": "gskril",
              "httpUrl": "https://github.com/gskril"
            },
            "twitter": {
              "handle": "gregskril",
              "httpUrl": "https://x.com/gregskril"
            }
          },
          "website": {
            "httpUrl": "https://gregskril.com/"
          },
          "header": {
            "httpUrl": "https://files.gregskril.com/cdn/QmfGaXqmqasCrKktBgD4AvvJb3DLndiKXdz457uBGLTFGK"
          }
        }
      }
    }
  }
}

Output matches a point in time snapshot GraphQL response from our alpha ENSNode instance. Live output depends on the configuration of your ENSNode instance and ENS state updates.

# 1. Create project
npm create vite@latest my-ens-app -- --template react-ts --no-interactive --no-immediate
cd my-ens-app
# 2. Install dependencies
npm install
npm install enskit@1.15.1 enssdk@1.15.1
# 3. Copy the TSX snippet above into src/App.tsx
# 4. Run
VITE_ENSNODE_URL=https://api.alpha.ensnode.io npm run dev

# 1. Create project
pnpm create vite@latest my-ens-app --template react-ts --no-interactive --no-immediate
cd my-ens-app
# 2. Install dependencies
pnpm install
pnpm add enskit@1.15.1 enssdk@1.15.1
# 3. Copy the TSX snippet above into src/App.tsx
# 4. Run
VITE_ENSNODE_URL=https://api.alpha.ensnode.io pnpm run dev

See the enskit docs for gql.tada plugin and provider setup.

cURL

# POST JSON to your ENSNode Omnigraph endpoint (same path enssdk uses).
curl -sS -X POST "https://api.alpha.ensnode.io/api/omnigraph" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "query DomainProfile($name: InterpretedName!) { domain(by: {name: $name}) { resolve { profile { description avatar { httpUrl } addresses { ethereum base solana bitcoin rootstock } socials { github { handle httpUrl } twitter { handle httpUrl } } website { httpUrl } header { httpUrl } } } } }",
  "variables": {"name":"gregskril.eth"}
}'

Response

{
  "data": {
    "domain": {
      "resolve": {
        "profile": {
          "description": "I like baking and building apps on web3 protocols.",
          "avatar": {
            "httpUrl": "https://gregskril.com/img/profile.jpg"
          },
          "addresses": {
            "ethereum": "0x179a862703a4adfb29896552df9e307980d19285",
            "base": "0x179a862703a4adfb29896552df9e307980d19285",
            "solana": "2JQANQn1kccapb7GT8XScf9qBy59uMo9vh9WwVQhwStJ",
            "bitcoin": "3NnpwUMGdGKuYaPDQagNXAgVXz9HdnJDNS",
            "rootstock": "0x179a862703A4AdFb29896552dF9e307980D19285"
          },
          "socials": {
            "github": {
              "handle": "gskril",
              "httpUrl": "https://github.com/gskril"
            },
            "twitter": {
              "handle": "gregskril",
              "httpUrl": "https://x.com/gregskril"
            }
          },
          "website": {
            "httpUrl": "https://gregskril.com/"
          },
          "header": {
            "httpUrl": "https://files.gregskril.com/cdn/QmfGaXqmqasCrKktBgD4AvvJb3DLndiKXdz457uBGLTFGK"
          }
        }
      }
    }
  }
}

Output matches a point in time snapshot GraphQL response from our alpha ENSNode instance. Live output depends on the configuration of your ENSNode instance and ENS state updates.

What you get in resolve.profile:

Addresses — keyed by chain (ethereum, solana, base, …) in chain-native encodings.
Social accounts — { handle, httpUrl } pairs, ready to link.
Avatar and header images — httpUrl values you can use directly in <img src="…" />, including derivation from NFT references per ENSIP-12.
Missing or invalid records — null, so you can render without extra guards.

Raw records — full protocol surface

resolve.records returns protocol-accurate resolver data: numeric coin types, arbitrary text keys, and unparsed bytes. This is the shape you would work with if you decoded resolver storage yourself — or if you need records that profile does not model.

This query below resolves raw records for a given name, such as addresses, texts, and contenthash.

Run in ENSAdmin Open an interactive playground to execute this example on our alpha ENSNode instance.

GraphQL

query DomainRecords($name: InterpretedName!) {
  domain(by: {name: $name}) {
    canonical {
      name {
        interpreted
      }
    }
    resolve {
      records {
        addresses(coinTypes: [60, 2147483658, 501]) {
          coinType
          address
        }
        texts(keys: ["description", "avatar", "url", "com.github", "com.twitter"]) {
          key
          value
        }
        contenthash
      }
    }
  }
}

Variables

{
  "name": "gregskril.eth"
}

Output

{
  "data": {
    "domain": {
      "canonical": {
        "name": {
          "interpreted": "gregskril.eth"
        }
      },
      "resolve": {
        "records": {
          "addresses": [
            {
              "coinType": 60,
              "address": "0x179a862703a4adfb29896552df9e307980d19285"
            },
            {
              "coinType": 2147483658,
              "address": "0x179a862703a4adfb29896552df9e307980d19285"
            },
            {
              "coinType": 501,
              "address": "0x1350bfe02357c8bc583d7514f44ba2c31821d8739160e7b79a0a94bc113a4f73"
            }
          ],
          "texts": [
            {
              "key": "description",
              "value": "I like baking and building apps on web3 protocols."
            },
            {
              "key": "avatar",
              "value": "https://gregskril.com/img/profile.jpg"
            },
            {
              "key": "url",
              "value": "https://gregskril.com/"
            },
            {
              "key": "com.github",
              "value": "gskril"
            },
            {
              "key": "com.twitter",
              "value": "gregskril"
            }
          ],
          "contenthash": "0xe30101701220f0bd3d5d672c6197d341797bb34d4a5e31fbb40c437fead8756213522b976ed9"
        }
      }
    }
  }
}

Output matches a point in time snapshot GraphQL response from our alpha ENSNode instance. Live output depends on the configuration of your ENSNode instance and ENS state updates.

Opens an editable StackBlitz project with this snippet.

TypeScript

import { createEnsNodeClient } from "enssdk/core";
import { asInterpretedName } from "enssdk";
import { graphql, omnigraph } from "enssdk/omnigraph";

const client = createEnsNodeClient({
  url: process.env.ENSNODE_URL || "https://api.alpha.ensnode.io"
}).extend(omnigraph);

const DomainRecordsQuery = graphql(`
  query DomainRecords($name: InterpretedName!) {
    domain(by: {name: $name}) {
      canonical {
        name {
          interpreted
        }
      }
      resolve {
        records {
          addresses(coinTypes: [60, 2147483658, 501]) {
            coinType
            address
          }
          texts(keys: ["description", "avatar", "url", "com.github", "com.twitter"]) {
            key
            value
          }
          contenthash
        }
      }
    }
  }
`);

const result = await client.omnigraph.query({
  query: DomainRecordsQuery,
  variables:   {
    name: asInterpretedName("gregskril.eth"),
  },
});

if (result.errors) throw new Error(JSON.stringify(result.errors));
console.log(JSON.stringify(result.data, null, 2));

Output

{
  "data": {
    "domain": {
      "canonical": {
        "name": {
          "interpreted": "gregskril.eth"
        }
      },
      "resolve": {
        "records": {
          "addresses": [
            {
              "coinType": 60,
              "address": "0x179a862703a4adfb29896552df9e307980d19285"
            },
            {
              "coinType": 2147483658,
              "address": "0x179a862703a4adfb29896552df9e307980d19285"
            },
            {
              "coinType": 501,
              "address": "0x1350bfe02357c8bc583d7514f44ba2c31821d8739160e7b79a0a94bc113a4f73"
            }
          ],
          "texts": [
            {
              "key": "description",
              "value": "I like baking and building apps on web3 protocols."
            },
            {
              "key": "avatar",
              "value": "https://gregskril.com/img/profile.jpg"
            },
            {
              "key": "url",
              "value": "https://gregskril.com/"
            },
            {
              "key": "com.github",
              "value": "gskril"
            },
            {
              "key": "com.twitter",
              "value": "gregskril"
            }
          ],
          "contenthash": "0xe30101701220f0bd3d5d672c6197d341797bb34d4a5e31fbb40c437fead8756213522b976ed9"
        }
      }
    }
  }
}

Output matches a point in time snapshot GraphQL response from our alpha ENSNode instance. Live output depends on the configuration of your ENSNode instance and ENS state updates.

# 1. Create project
mkdir -p my-ens-script/src && cd my-ens-script
npm init -y && touch src/index.ts
npm pkg set type=module scripts.start="tsx src/index.ts"
# 2. Install dependencies
npm install enssdk@1.15.1 && npm install -D tsx typescript @types/node
# 3. Paste the TypeScript snippet above into src/index.ts
# 4. Run
ENSNODE_URL=https://api.alpha.ensnode.io npm start

# 1. Create project
mkdir -p my-ens-script/src && cd my-ens-script
pnpm init && touch src/index.ts
pnpm pkg set type=module scripts.start="tsx src/index.ts"
# 2. Install dependencies
pnpm add enssdk@1.15.1 && pnpm add -D tsx typescript @types/node
# 3. Paste the TypeScript snippet above into src/index.ts
# 4. Run
ENSNODE_URL=https://api.alpha.ensnode.io pnpm start

See the enssdk docs for gql.tada plugin and tsconfig setup.

Opens an editable StackBlitz project with this snippet.

TSX (React)

import { OmnigraphProvider, useOmnigraphQuery, graphql } from "enskit/react/omnigraph";
import { createEnsNodeClient } from "enssdk/core";
import { asInterpretedName } from "enssdk";
import { omnigraph } from "enssdk/omnigraph";

const client = createEnsNodeClient({
  url: import.meta.env.VITE_ENSNODE_URL || "https://api.alpha.ensnode.io"
}).extend(omnigraph);

const DomainRecordsQuery = graphql(`
  query DomainRecords($name: InterpretedName!) {
    domain(by: {name: $name}) {
      canonical {
        name {
          interpreted
        }
      }
      resolve {
        records {
          addresses(coinTypes: [60, 2147483658, 501]) {
            coinType
            address
          }
          texts(keys: ["description", "avatar", "url", "com.github", "com.twitter"]) {
            key
            value
          }
          contenthash
        }
      }
    }
  }
`);

function DomainRecordsResult() {
  const [result] = useOmnigraphQuery({
    query: DomainRecordsQuery,
    variables:     {
      name: asInterpretedName("gregskril.eth"),
    },
  });
  const { data, fetching, error } = result;
  if (!data && fetching) return <p>Loading…</p>;
  if (error) return <p>Error: {error.message}</p>;
  if (!data) return <p>No data returned.</p>;
  const formatted = JSON.stringify(
    data,
    (_, value) => (typeof value === "bigint" ? value.toString() : value),
    2,
  );
  return <code>{formatted}</code>;
}

export default function App() {
  return (
    <OmnigraphProvider client={client}>
      <DomainRecordsResult />
    </OmnigraphProvider>
  );
}

Output

{
  "data": {
    "domain": {
      "canonical": {
        "name": {
          "interpreted": "gregskril.eth"
        }
      },
      "resolve": {
        "records": {
          "addresses": [
            {
              "coinType": 60,
              "address": "0x179a862703a4adfb29896552df9e307980d19285"
            },
            {
              "coinType": 2147483658,
              "address": "0x179a862703a4adfb29896552df9e307980d19285"
            },
            {
              "coinType": 501,
              "address": "0x1350bfe02357c8bc583d7514f44ba2c31821d8739160e7b79a0a94bc113a4f73"
            }
          ],
          "texts": [
            {
              "key": "description",
              "value": "I like baking and building apps on web3 protocols."
            },
            {
              "key": "avatar",
              "value": "https://gregskril.com/img/profile.jpg"
            },
            {
              "key": "url",
              "value": "https://gregskril.com/"
            },
            {
              "key": "com.github",
              "value": "gskril"
            },
            {
              "key": "com.twitter",
              "value": "gregskril"
            }
          ],
          "contenthash": "0xe30101701220f0bd3d5d672c6197d341797bb34d4a5e31fbb40c437fead8756213522b976ed9"
        }
      }
    }
  }
}

Output matches a point in time snapshot GraphQL response from our alpha ENSNode instance. Live output depends on the configuration of your ENSNode instance and ENS state updates.

# 1. Create project
npm create vite@latest my-ens-app -- --template react-ts --no-interactive --no-immediate
cd my-ens-app
# 2. Install dependencies
npm install
npm install enskit@1.15.1 enssdk@1.15.1
# 3. Copy the TSX snippet above into src/App.tsx
# 4. Run
VITE_ENSNODE_URL=https://api.alpha.ensnode.io npm run dev

# 1. Create project
pnpm create vite@latest my-ens-app --template react-ts --no-interactive --no-immediate
cd my-ens-app
# 2. Install dependencies
pnpm install
pnpm add enskit@1.15.1 enssdk@1.15.1
# 3. Copy the TSX snippet above into src/App.tsx
# 4. Run
VITE_ENSNODE_URL=https://api.alpha.ensnode.io pnpm run dev

See the enskit docs for gql.tada plugin and provider setup.

cURL

# POST JSON to your ENSNode Omnigraph endpoint (same path enssdk uses).
curl -sS -X POST "https://api.alpha.ensnode.io/api/omnigraph" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "query DomainRecords($name: InterpretedName!) { domain(by: {name: $name}) { canonical { name { interpreted } } resolve { records { addresses(coinTypes: [60, 2147483658, 501]) { coinType address } texts(keys: [\"description\", \"avatar\", \"url\", \"com.github\", \"com.twitter\"]) { key value } contenthash } } } }",
  "variables": {"name":"gregskril.eth"}
}'

Response

{
  "data": {
    "domain": {
      "canonical": {
        "name": {
          "interpreted": "gregskril.eth"
        }
      },
      "resolve": {
        "records": {
          "addresses": [
            {
              "coinType": 60,
              "address": "0x179a862703a4adfb29896552df9e307980d19285"
            },
            {
              "coinType": 2147483658,
              "address": "0x179a862703a4adfb29896552df9e307980d19285"
            },
            {
              "coinType": 501,
              "address": "0x1350bfe02357c8bc583d7514f44ba2c31821d8739160e7b79a0a94bc113a4f73"
            }
          ],
          "texts": [
            {
              "key": "description",
              "value": "I like baking and building apps on web3 protocols."
            },
            {
              "key": "avatar",
              "value": "https://gregskril.com/img/profile.jpg"
            },
            {
              "key": "url",
              "value": "https://gregskril.com/"
            },
            {
              "key": "com.github",
              "value": "gskril"
            },
            {
              "key": "com.twitter",
              "value": "gregskril"
            }
          ],
          "contenthash": "0xe30101701220f0bd3d5d672c6197d341797bb34d4a5e31fbb40c437fead8756213522b976ed9"
        }
      }
    }
  }
}

Output matches a point in time snapshot GraphQL response from our alpha ENSNode instance. Live output depends on the configuration of your ENSNode instance and ENS state updates.

Reverse resolution — primary name

Wallets and explorers usually start from an address, not a name. Reverse resolution answers a simple question: what name does this address want to be known by? On a given chain, that is its primary name (ENSIP-19). If the address has not set one, the result is null — safe to render like any other missing profile field.

Most apps do not stop there. Once you have the name, you still need avatar, bio, and links — a second forward resolution step. The Omnigraph chains both into one request: address → primary name → profile. Note that resolve.profile schema is the same as in Domain.resolve.profile, so the only “new” concept here is the address-to-name lookup.

This query below loads a primary name for an account on Ethereum, including profile information.

Run in ENSAdmin Open an interactive playground to execute this example on our alpha ENSNode instance.

GraphQL

query AccountPrimaryName($address: Address!) {
  account(by: { address: $address }) {
    address
    resolve {
      primaryName(by: { chainName: ETHEREUM }) {
        name { interpreted beautified }
        resolve {
          profile {
            description
            socials {
              twitter {
                httpUrl
              }
            }
          }
        }
      }
    }
  }
}

Variables

{
  "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045"
}

Output

{
  "data": {
    "account": {
      "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "resolve": {
        "primaryName": {
          "name": {
            "interpreted": "vitalik.eth",
            "beautified": "vitalik.eth"
          },
          "resolve": {
            "profile": {
              "description": "mi pinxe lo crino tcati",
              "socials": {
                "twitter": {
                  "httpUrl": "https://x.com/VitalikButerin"
                }
              }
            }
          }
        }
      }
    }
  }
}

Output matches a point in time snapshot GraphQL response from our alpha ENSNode instance. Live output depends on the configuration of your ENSNode instance and ENS state updates.

Opens an editable StackBlitz project with this snippet.

TypeScript

import { createEnsNodeClient } from "enssdk/core";
import { graphql, omnigraph } from "enssdk/omnigraph";

const client = createEnsNodeClient({
  url: process.env.ENSNODE_URL || "https://api.alpha.ensnode.io"
}).extend(omnigraph);

const AccountPrimaryNameQuery = graphql(`
  query AccountPrimaryName($address: Address!) {
    account(by: { address: $address }) {
      address
      resolve {
        primaryName(by: { chainName: ETHEREUM }) {
          name { interpreted beautified }
          resolve {
            profile {
              description
              socials {
                twitter {
                  httpUrl
                }
              }
            }
          }
        }
      }
    }
  }
`);

const result = await client.omnigraph.query({
  query: AccountPrimaryNameQuery,
  variables:   {
    address: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  },
});

if (result.errors) throw new Error(JSON.stringify(result.errors));
console.log(JSON.stringify(result.data, null, 2));

Output

{
  "data": {
    "account": {
      "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "resolve": {
        "primaryName": {
          "name": {
            "interpreted": "vitalik.eth",
            "beautified": "vitalik.eth"
          },
          "resolve": {
            "profile": {
              "description": "mi pinxe lo crino tcati",
              "socials": {
                "twitter": {
                  "httpUrl": "https://x.com/VitalikButerin"
                }
              }
            }
          }
        }
      }
    }
  }
}

Output matches a point in time snapshot GraphQL response from our alpha ENSNode instance. Live output depends on the configuration of your ENSNode instance and ENS state updates.

# 1. Create project
mkdir -p my-ens-script/src && cd my-ens-script
npm init -y && touch src/index.ts
npm pkg set type=module scripts.start="tsx src/index.ts"
# 2. Install dependencies
npm install enssdk@1.15.1 && npm install -D tsx typescript @types/node
# 3. Paste the TypeScript snippet above into src/index.ts
# 4. Run
ENSNODE_URL=https://api.alpha.ensnode.io npm start

# 1. Create project
mkdir -p my-ens-script/src && cd my-ens-script
pnpm init && touch src/index.ts
pnpm pkg set type=module scripts.start="tsx src/index.ts"
# 2. Install dependencies
pnpm add enssdk@1.15.1 && pnpm add -D tsx typescript @types/node
# 3. Paste the TypeScript snippet above into src/index.ts
# 4. Run
ENSNODE_URL=https://api.alpha.ensnode.io pnpm start

See the enssdk docs for gql.tada plugin and tsconfig setup.

Opens an editable StackBlitz project with this snippet.

TSX (React)

import { OmnigraphProvider, useOmnigraphQuery, graphql } from "enskit/react/omnigraph";
import { createEnsNodeClient } from "enssdk/core";
import { omnigraph } from "enssdk/omnigraph";

const client = createEnsNodeClient({
  url: import.meta.env.VITE_ENSNODE_URL || "https://api.alpha.ensnode.io"
}).extend(omnigraph);

const AccountPrimaryNameQuery = graphql(`
  query AccountPrimaryName($address: Address!) {
    account(by: { address: $address }) {
      address
      resolve {
        primaryName(by: { chainName: ETHEREUM }) {
          name { interpreted beautified }
          resolve {
            profile {
              description
              socials {
                twitter {
                  httpUrl
                }
              }
            }
          }
        }
      }
    }
  }
`);

function AccountPrimaryNameResult() {
  const [result] = useOmnigraphQuery({
    query: AccountPrimaryNameQuery,
    variables:     {
      address: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
    },
  });
  const { data, fetching, error } = result;
  if (!data && fetching) return <p>Loading…</p>;
  if (error) return <p>Error: {error.message}</p>;
  if (!data) return <p>No data returned.</p>;
  const formatted = JSON.stringify(
    data,
    (_, value) => (typeof value === "bigint" ? value.toString() : value),
    2,
  );
  return <code>{formatted}</code>;
}

export default function App() {
  return (
    <OmnigraphProvider client={client}>
      <AccountPrimaryNameResult />
    </OmnigraphProvider>
  );
}

Output

{
  "data": {
    "account": {
      "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "resolve": {
        "primaryName": {
          "name": {
            "interpreted": "vitalik.eth",
            "beautified": "vitalik.eth"
          },
          "resolve": {
            "profile": {
              "description": "mi pinxe lo crino tcati",
              "socials": {
                "twitter": {
                  "httpUrl": "https://x.com/VitalikButerin"
                }
              }
            }
          }
        }
      }
    }
  }
}

Output matches a point in time snapshot GraphQL response from our alpha ENSNode instance. Live output depends on the configuration of your ENSNode instance and ENS state updates.

# 1. Create project
npm create vite@latest my-ens-app -- --template react-ts --no-interactive --no-immediate
cd my-ens-app
# 2. Install dependencies
npm install
npm install enskit@1.15.1 enssdk@1.15.1
# 3. Copy the TSX snippet above into src/App.tsx
# 4. Run
VITE_ENSNODE_URL=https://api.alpha.ensnode.io npm run dev

# 1. Create project
pnpm create vite@latest my-ens-app --template react-ts --no-interactive --no-immediate
cd my-ens-app
# 2. Install dependencies
pnpm install
pnpm add enskit@1.15.1 enssdk@1.15.1
# 3. Copy the TSX snippet above into src/App.tsx
# 4. Run
VITE_ENSNODE_URL=https://api.alpha.ensnode.io pnpm run dev

See the enskit docs for gql.tada plugin and provider setup.

cURL

# POST JSON to your ENSNode Omnigraph endpoint (same path enssdk uses).
curl -sS -X POST "https://api.alpha.ensnode.io/api/omnigraph" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "query AccountPrimaryName($address: Address!) { account(by: { address: $address }) { address resolve { primaryName(by: { chainName: ETHEREUM }) { name { interpreted beautified } resolve { profile { description socials { twitter { httpUrl } } } } } } } }",
  "variables": {"address":"0xd8da6bf26964af9d7eed9e03e53415d37aa96045"}
}'

Response

{
  "data": {
    "account": {
      "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "resolve": {
        "primaryName": {
          "name": {
            "interpreted": "vitalik.eth",
            "beautified": "vitalik.eth"
          },
          "resolve": {
            "profile": {
              "description": "mi pinxe lo crino tcati",
              "socials": {
                "twitter": {
                  "httpUrl": "https://x.com/VitalikButerin"
                }
              }
            }
          }
        }
      }
    }
  }
}

Output matches a point in time snapshot GraphQL response from our alpha ENSNode instance. Live output depends on the configuration of your ENSNode instance and ENS state updates.

Breaking down the example above:

Start from an address — pass any wallet address; the query looks up that account’s ENS identity.
Pick a chain — primary names are per-chain (e.g. Ethereum mainnet). Use friendly chain names like ETHEREUM or BASE instead of raw coin types.
Display the name — beautified is ready for UI rendering; interpreted is the stable form for lookups and links. See Beautified Name.
Load the profile in the same request — avatar, bio, and social links are forward-resolved from the primary name without a second API call.

AI and agent integration

For AI agents, clean structured inputs matter most. resolve.profile delivers addresses keyed by chain name rather than coin types, social links as { handle, httpUrl } pairs, and invalid or unset records normalized to null — filtering out noise before it reaches your prompt.

AI/LLM Tooling 🤖

ENS Resolution

Forward resolution — interpreted profile

enssdk package manager setup

enskit package manager setup

Raw records — full protocol surface

enssdk package manager setup

enskit package manager setup

Reverse resolution — primary name

enssdk package manager setup

enskit package manager setup

AI and agent integration