Skip to main content

​
ENS Offchain Subnames + RainbowKit Starter Kit

A Next.js starter integrating the Offchain Manager SDK with RainbowKit for creating and managing offchain ENS subnames.

​
Features

  • RainbowKit UI with offchain subname creation and fetch logic
  • Reverse resolution for addresses, e.g., 0x23... → happy.offchainsub.eth
Repository: thenamespace/ens-subnames-rainbowkit-template

​
Prerequisites

  • Node.js (v18 or later)
  • An ENS name (e.g., offchainsub.eth)
  • Namespace API key from the Dev Portal

​
Setup

1

Clone and install

git clone https://github.com/thenamespace/ens-subnames-rainbowkit-template.git
cd ens-subnames-rainbowkit-template
npm install
2

Environment variables

Create a .env.local file in the root directory:
# Your ENS name (eg. offchainsub.eth)
NEXT_PUBLIC_ENS_NAME=yourname

# Your Namespace API key (keep this secret!)
NAMESPACE_API_KEY=ns_live_xxxxxxxxxx
3

Configure your ENS name

  1. Visit the Namespace Dev Portal
  2. Change the resolver for your ENS name to Namespace’s resolver
  3. Generate and copy your API key
  4. Add both to your .env.local file
4

Run the development server

npm run dev
Open http://localhost:3000 to see the application.
5

It's ready!

Create subname interface with form to create a new offchain subname

​
What’s included

​
🔗 RainbowKit Integration

  • Custom connect button with Namespace subname support
  • Account modal with subname creation functionality
  • Automatic primary name resolution

​
File Structure

src/
├── app/
│   ├── api/subname/create/route.ts    # Server-side subname creation
│   ├── page.tsx                       # Main demo page
│   └── providers.tsx                  # RainbowKit & Wagmi setup
├── components/
│   └── kit/
│       ├── AccountModal.tsx           # Account management modal
│       └── CustomConnectButton.tsx    # Custom connect button
├── hooks/
│   ├── use-subnames.ts               # Subname fetching hooks
│   └── use-subname-creation.ts       # Subname creation hooks
└── lib/
    ├── namespace.ts                   # Server-side client (with API key)
    └── namespace-client.ts            # Client-side client (read-only)

​
🏗️ Architecture

  • Server-side Namespace client (/src/lib/namespace.ts) - Uses API key securely for write operations
  • Client-side Namespace client (/src/lib/namespace-client.ts) - For read-only operations without API key exposure
  • API route (/src/app/api/subname/create/route.ts) - Server-side subname creation endpoint

​
🪝 Custom Hooks

  • useSubnames - Fetch subnames for an address
  • useFirstSubname - Get the primary subname for an address
  • usePreferredIdentity - Intelligent name resolution (subname → ENS → truncated address)
  • useCreateSubname - Create new subnames with validation
  • useSubnameAvailability - Check if a subname is available

​
📡 API Endpoints

  • POST /api/subname/create - Create subnames with custom address and text records

​
Security & Limitations

​
⚠️ Important Security Notes

  • Never expose your Namespace API key to the client side
  • API key is only used in server-side code (/src/lib/namespace.ts and API routes)
  • Client-side operations use the public client without API key

​
📊 Rate Limits

  • Up to 2,000 subnames can be created per API key to prevent abuse
  • Need more? Contact us on the Builders Group

​
References