How To Create Offchain Subnames

Overview

This guide walks you through creating and using offchain ENS subnames with the @thenamespace/offchain-manager SDK. You’ll be able to create a subname, and then read records.

Prerequisites

Node.js 18+ and a package manager (npm or yarn)
An ENS name you manage (e.g., myensname.eth)
A Namespace API key (from the Namespace App)

Get an API Key

Follow this guide to create and copy your API key from the Namespace App.

Install and initialize the SDK

Install the Offchain SDK and dotenv to load your API key from an environment variable:

npm
yarn

npm install @thenamespace/offchain-manager dotenv

yarn add @thenamespace/offchain-manager dotenv

Initialise the client with the network you want to use and your API key. We recommend setting your API key via an environment variable and keeping it secret by using server-side code.

import 'dotenv/config';
import { createOffchainClient } from '@thenamespace/offchain-manager';

// Required: set NAMESPACE_API_KEY in your environment
const API_KEY = process.env.NAMESPACE_API_KEY as string;
if (!API_KEY) throw new Error('Missing NAMESPACE_API_KEY');

// Use 'sepolia' for testing, 'mainnet' for production
export const client = createOffchainClient({ 
  mode: 'mainnet', 
  timeout: 5000,
  defaultApiKey: API_KEY,
});

console.log('Offchain client initialized');

Check if a subname is available

Use isSubnameAvailable before creating a subname to avoid overwriting an existing one.

import { client } from './index';

async function main() {
  const subname = 'alice.myensname.eth';
  const { isAvailable } = await client.isSubnameAvailable(subname);
  console.log('isAvailable:', isAvailable);
}

main().catch((err) => {
  console.error('Availability check failed:', err);
  process.exit(1);
});

Expected output (if available):

isAvailable: true

Create the subname with optional records

You can use the owner field to filter subnames by their associated address, enabling efficient reverse lookups (from address to name).

Create a subname under your parent name. You can include text records, address records, owner, and metadata.

import { client } from './index';
import { ChainName } from '@thenamespace/offchain-manager';

async function main() {
  const PARENT_NAME = 'myensname.eth';
  const SUB_LABEL = 'alice'; // results in alice.myensname.eth
  const OWNER_ADDRESS = '0x1234567890abcdef1234567890abcdef12345678';

  // After checking the subname is available, create it with the following parameters:

  await client.createSubname({
    label: SUB_LABEL,
    parentName: PARENT_NAME,
    texts: [
      { key: 'name', value: 'Alice' },
      { key: 'url', value: 'https://example.com' },
    ],
    addresses: [
      { chain: ChainName.Ethereum, value: OWNER_ADDRESS },
    ],
    owner: OWNER_ADDRESS,
    metadata: [{ key: 'sender', value: OWNER_ADDRESS }],
  });

  console.log(`Created ${SUB_LABEL}.${PARENT_NAME}`);
}

main().catch((err) => {
  console.error('Create subname failed:', err);
  process.exit(1);
});

import 'dotenv/config';
import { createOffchainClient } from '@thenamespace/offchain-manager';

// Required: set NAMESPACE_API_KEY in your environment
const API_KEY = process.env.NAMESPACE_API_KEY as string;
if (!API_KEY) throw new Error('Missing NAMESPACE_API_KEY');

// Use 'sepolia' for testing, 'mainnet' for production
export const client = createOffchainClient({ 
 mode: 'mainnet', 
 timeout: 5000,
 defaultApiKey: API_KEY,
});

console.log('Offchain client initialized');

Expected output:

Created alice.myensname.eth

Filter subnames by owner

We recommend associating a single address with a single subname to do reverse lookup.

Fetch all subnames you own or created by filtering on owner (or by metadata).

import { client } from './index';

async function main() {
  const PARENT_NAME = 'myensname.eth';
  const OWNER_ADDRESS = '0x1234567890abcdef1234567890abcdef12345678';

  // Get all subnames owned by the address
  const page = await client.getFilteredSubnames({
    parentName: PARENT_NAME,
    owner: OWNER_ADDRESS,
    page: 1,
    size: 5,
  });

  console.log(JSON.stringify(page.items, null, 2));
}

main();

Example output:

[
  {
    "fullName": "alice.myensname.eth",
    "parentName": "myensname.eth",
    "label": "alice",
    "texts": { "name": "Alice", "url": "https://example.com" },
    "addresses": { "60": "0x1234567890abcdef1234567890abcdef12345678" },
    "metadata": { "sender": "0x1234567890abcdef1234567890abcdef12345678" },
    "owner": "0x1234567890abcdef1234567890abcdef12345678"
  }
]

Look up text records

Retrieve a single text record or all text records on a subname.

import { client } from './index';

async function main() {
  const subname = 'alice.myensname.eth';

  // You can retrieve all text records on a subname
  const all = await client.getTextRecords(subname);

  // You can also retrieve a single text record based on a key on a subname
  const { record: name } = await client.getTextRecord(subname, 'name');

  console.log('all text records:', all);
  console.log('name:', name);
}

main();

Example output:

all text records: { name: 'Alice', url: 'https://example.com' }
name: Alice

Look up address records

Address records are included in the subname response. A simple way to read them is via getFilteredSubnames and then inspecting addresses.

import { client } from './index';

async function main() {
  const subnamesPage = await client.getFilteredSubnames({ parentName: 'myensname.eth', labelSearch: 'alice' });
  const item = subnamesPage.items.find((i) => i.fullName === 'alice.myensname.eth');
  console.log('addresses:', item?.addresses);
}

main();

Example output:

addresses: { "60": "0x1234567890abcdef1234567890abcdef12345678" }

Next steps

Update records on an existing subname using updateSubname
Explore more filters with getFilteredSubnames
See supported chains in ChainName

ENS Client Compatibility

Subnames created with the Offchain SDK can be accessed and resolved using any of the eligible ENS client libraries like wagmi, viem, ethers, and others listed in the ENS Tools & Libraries documentation.

Reverse Resolution Limitation: Offchain subnames do not support reverse resolution, so you cannot fetch a profile from an address. However, you can still set address records on offchain subnames for forward resolution.

Getting Started

How to Guides

Integrations

API Reference

SDK Reference

Architecture

How To Create Offchain Subnames

Overview

Prerequisites

Get an API Key

Next steps

ENS Client Compatibility

​Overview

​Prerequisites

Get an API Key

​Next steps

​ENS Client Compatibility

Overview

Prerequisites

Next steps

ENS Client Compatibility