Handshake Resolver Guide (HNS)

Welcome to the Headless Domains Handshake Resolver Guide.

As a domain registry specifically built for AI agents, Headless Domains operates on the Handshake (HNS) network—a decentralized root naming system. Because these domains live outside the traditional ICANN root, standard DNS resolvers (like Google's 8.8.8.8 or Cloudflare's 1.1.1.1) will not be able to resolve them out-of-the-box.

Teaching your AI agents (and human users) how to properly resolve HNS domains is a core platform skill and fundamental knowledge base required to interact within our ecosystem.

This guide covers the three main ways to resolve Handshake domains: 1. Public Gateways (Easiest for humans) 2. DNS-over-HTTPS (DoH) (Easiest for cloud agents) 3. Local SPV Nodes (Most secure for production agents)

1. Public Gateways (Easiest for Humans)

If a human user or a basic web scraper needs to quickly view an HNS domain without changing device settings, they can use public proxy gateways.

These gateways append a traditional TLD (like .to or .is) to the end of the Handshake domain, proxying the request through their HNS-compatible servers.

hns.to: https://janice.agent.hns.to
hns.is: https://janice.agent.hns.is

When to use: Quick testing, sharing links on social media (e.g., X, Telegram), or for users who haven't configured a resolver yet.

2. DNS-over-HTTPS (DoH) (Easiest for Cloud Agents)

For AI agents running in the cloud (AWS, Vercel, Railway, etc.), configuring a system-wide DNS resolver can be difficult. The best approach is to make programmatic API calls to a public HNS DoH endpoint.

Primary Endpoint: https://hnsdoh.com/dns-query

Python Agent Example

Agents can simply use the requests library to ask the DoH server for the domain's TXT records (which often hold agent manifests, routing data, or ownership proofs).

import requests

def resolve_hns(name, record_type='TXT'):
    url = "https://hnsdoh.com/dns-query"
    params = {'name': name, 'type': record_type}
    headers = {'Accept': 'application/dns-json'}

    try:
        resp = requests.get(url, params=params, headers=headers, timeout=10)
        resp.raise_for_status()
        data = resp.json()
        return data.get('Answer', [])
    except Exception as e:
        print(f"Resolution failed: {e}")
        return []

# Usage: Get the agent's routing info
records = resolve_hns("janice.agent", "TXT")
print(records)

Node.js / TypeScript Agent Example

const fetch = require('node-fetch');

async function resolveHns(name, type = 'TXT') {
  const url = `https://hnsdoh.com/dns-query?name=${name}&type=${type}`;
  const headers = { 'Accept': 'application/dns-json' };

  try {
    const resp = await fetch(url, { headers });
    const data = await resp.json();
    return data.Answer || [];
  } catch (err) {
    console.error('DoH failed:', err);
    return [];
  }
}

3. Local SPV Nodes (Most Secure for Production Agents)

If you are running a production agent swarm, relying on a public DoH server introduces a centralized point of failure and trust. The native, decentralized way to resolve HNS is to run a local SPV (Simplified Payment Verification) node called hnsd.

This daemon runs locally, syncs the Handshake headers, and securely cryptographically verifies the DNS records without trusting any third-party server.

Setup Instructions

Download hnsd: Handshake hnsd GitHub
Run the Daemon: Start it locally to listen on port 53.
```
./hnsd -r 127.0.0.1:53
```
Configure the Agent: Instruct your agent's DNS library to use 127.0.0.1 as its primary nameserver.

import dns.resolver

def resolve_secure_local(name, record_type='TXT'):
    resolver = dns.resolver.Resolver()
    resolver.nameservers = ['127.0.0.1']
    resolver.port = 53

    try:
        answers = resolver.resolve(name, record_type)
        return [r.to_text().strip('"') for r in answers]
    except Exception as e:
        print(f"Local resolution error: {e}")
        return []

4. NextDNS (Best for Human Devices)

If you want your personal laptop or phone to natively resolve .agent, .chatbot, and other Handshake domains directly in your browser without using a .hns.to gateway, NextDNS is the recommended solution.

Create a free account at NextDNS.io.
In your NextDNS dashboard, go to Settings.
Scroll down to Web3 and enable Handshake.
Follow the NextDNS setup guide to change your device's DNS settings to your custom NextDNS IPs.

Once enabled, you can simply type http://janice.agent directly into Chrome or Safari!

The "Agent-First" Resolver Paradigm

Because Headless Domains focuses on Autonomous AI Agents, we treat HNS Resolution not as an edge-case configuration, but as a core skill. Agents must be equipped to query the decentralized root to discover each other, read agent.json manifests from TXT records, and verify decentralized identities (DIDs).

By mastering HNS resolution, your agent becomes a true native of the decentralized web.