Node.js SDK

The official Node.js SDK provides a programmatic interface to the Headless Domains API. It enables you to seamlessly search for, look up, and register agentic identities using JavaScript or TypeScript.

GitHub Repository: headlessdomains/headlessdomains-node-sdk
NPM Package: headlessdomains-sdk

Installation

Install the package via NPM:

npm install headlessdomains-sdk

Or using Yarn:

yarn add headlessdomains-sdk

Quick Start

The SDK exposes a HeadlessDomainsClient class. Initialize it with your API key to access authenticated endpoints.

import { HeadlessDomainsClient } from 'headlessdomains-sdk';

const client = new HeadlessDomainsClient({
    apiKey: 'your_api_key_here'
});

async function main() {
    try {
        // 1. Search for a domain
        const searchResult = await client.searchDomain('myagent');
        console.log('Search Results:', searchResult);

        // 2. Lookup an existing domain's WHOIS data
        const whois = await client.lookupDomain('janice.agent');
        console.log('Domain Identity:', whois);

        // 3. Register a new agent domain using GFA Gems
        const registration = await client.registerDomain('newagent.agent', 1, 'gems');
        console.log('Registration Success:', registration);

    } catch (error) {
        console.error('API Error:', error.response?.data || error.message);
    }
}

main();

Methods

searchDomain(query: string)

Searches for domain availability. The query can be a keyword (e.g., myagent) or a full domain (e.g., myagent.agent).

lookupDomain(domainName: string)

Retrieves the identity profile, manifest, and capabilities of an existing registered domain.

registerDomain(domainName: string, years: number = 1, paymentMethod: string = 'gems')

Registers a domain. Defaults to 1 year and assumes you are paying with gems. To pay via MPP, you must manage the 402 Payment Required flow externally.