AgentDomain Documentation

Identity infrastructure for the agent economy.

Domain + Basename + ENS + DNS + SSL + Email in one checkout. Works with ElizaOS, AgentKit, OpenAI SDK, and Anthropic SDK.

Works with your agent stack

First-class integrations for ElizaOS and Coinbase AgentKit. Tool adapters for OpenAI SDK and Anthropic SDK. Any other framework can use the REST API or MCP server directly.

Coinbase AgentKit

@agentdomain/agentkit-plugin
import { AgentDomainActionProvider }
  from '@agentdomain/agentkit-plugin';

const agentkit = await AgentKit.from({
  walletProvider: cdpWalletProvider,
  actionProviders: [
    new AgentDomainActionProvider(),
  ],
});

// Agent calls:
// → register_agent_identity
// → quote_agent_registration
// → search_agents

Native action provider. Agents get register, quote, and search as first-class actions.

ElizaOS

@agentdomain/eliza-plugin
// character.ts
import { agentDomainPlugin } from '@agentdomain/eliza-plugin';

const character: Character = {
  name: 'HelpfulAgent',
  plugins: [agentDomainPlugin],
};

// Agent says:
// "Register me as helpful-bot.ai with email"
// → REGISTER_IDENTITY action triggers
// → domain + basename + email provisioned

Drop-in plugin. Your Eliza agent gets REGISTER_IDENTITY, SEARCH_AGENTS actions automatically.

OpenAI SDK

@agentdomain/sdk
import {
  AgentDomain,
  createOpenAITools,
  runAgentDomainTool,
  formatAgentDomainToolResult,
} from '@agentdomain/sdk';

const ad = new AgentDomain({
  walletClient,
  publicClient,
  renewalVaultAddress: '0xRenewalVault...',
});

const tools = createOpenAITools();

const response = await openai.chat.completions
  .create({
    model: 'gpt-4',
    messages: [...],
    tools,
  });

const toolCall = response.choices[0]
  ?.message?.tool_calls?.[0];
const result = await runAgentDomainTool(
  ad,
  toolCall.function.name,
  JSON.parse(toolCall.function.arguments),
);
// → domain registered, NFT minted

Tool definitions for Chat Completions API. Models call registration, search, renewal status, and enable_auto_renew as native tools.

Anthropic SDK

@agentdomain/sdk
import {
  AgentDomain,
  createAnthropicTools,
  runAgentDomainTool,
  formatAgentDomainToolResult,
} from '@agentdomain/sdk';

const ad = new AgentDomain({
  walletClient,
  publicClient,
  renewalVaultAddress: '0xRenewalVault...',
});

const tools = createAnthropicTools();

const msg = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  messages: [...],
  tools,
});

const toolUse = msg.content.find(
  (b) => b.type === 'tool_use',
);
const result = await runAgentDomainTool(
  ad, toolUse.name, toolUse.input,
);
// → domain registered, NFT minted

Tool definitions for Messages API. Models call the same agent-domain tools with Anthropic-native input_schema format.

Getting Started

From UI, SDK, or any agent wallet — complete flow in one call.

1
Connect a wallet on Base mainnet.
2
Choose a name + TLD (.xyz, .com, .ai, etc).
3
Review the live USDC quote and sign the x402 payment.
4
AgentDomain provisions domain, DNS, SSL, Basename, ENS, email, and mints the AgentID NFT.
5
Open the agent page and use the Auto-Renew switch with the owner wallet.
6
Fund the RenewalVault for hands-free autonomous renewal.
7
That's it — your agent has a real internet identity.

TypeScript SDK

const quote = await agentDomain.quote({
  preferredName: 'atlas',
  tld: 'com',
  years: 3,
  registerBasename: false,
  registerEns: false,
  emailEnabled: true,
});

const identity = await agentDomain.register({
  preferredName: 'atlas',
  tld: 'com',
  years: 3,
  autoRenew: true,
  registerBasename: false,
  registerEns: false,
  emailEnabled: true,
});

The @agentdomain/sdk handles the 402 challenge, signs EIP-3009 from your wallet, and completes registration in one async call. Set optional flags to false when the agent should skip Basename, ENS, or email.

Pricing Rules

The quote endpoint is the source of truth for web checkout, SDK, MCP, and agent plugins.

Always included
Domain, DNS, AgentID NFT, service fee, SSL certification
SSL certification
$1.20 per year, charged on purchase and renewal
Optional flags
registerBasename, registerEns, emailEnabled
Skip optional cost
Set the optional flag to false in web, SDK, MCP, or plugin calls

API Reference

Every endpoint available to manage your agent’s identity. State-modifying endpoints require SIWE authentication (web dashboard) or API Keys (agents).

USDC x402 Secured

Registration & Pricing

Check Availability
GET
/api/v1/domains/availability?name=atlas&tld=com

Checks domain, Basename, and ENS availability independently.

Get Pricing Quote
GET
/api/v1/agents/quote?preferredName=atlas&tld=com&years=3

Returns live pricing for the identity bundle, including multi-year discounts.

Register Identity (x402)
POST
/api/v1/agents/register

Requires x402 payment challenge. Provisions the complete identity bundle.

Agent Management

Get Agent Details
GET
/api/v1/agents/:id

Returns identity state, expiration dates, and metadata.

Reconfigure SSL
POST
/api/v1/agents/:id/ssl

Rebuilds the Cloudflare SaaS hostname and syncs Spaceship DNS validation records. Owner/API key only.

DNS Management

List DNS Records
GET
/api/v1/agents/:id/dns

Returns all DNS records for the agent's domain.

Create DNS Record
POST
/api/v1/agents/:id/dns

Add a new DNS record. Syncs instantly to Cloudflare.

Update DNS Record
PATCH
/api/v1/agents/:id/dns/:recordId

Modify an existing DNS record.

Delete DNS Record
DELETE
/api/v1/agents/:id/dns/:recordId

Remove a DNS record from the database and Cloudflare.

Email Infrastructure

Get Email Inbox
GET
/api/v1/agents/:id/email

Retrieve all inbound and outbound messages for the agent.

Send Email
POST
/api/v1/agents/:id/email/send

Send an outbound email from agent@yourdomain.com.

Update Message Status
PATCH
/api/v1/agents/:id/email/:messageId

Mark an email message as read or unread.

Manage Blocklist
POST
/api/v1/agents/:id/email/blocklist

Retrieve (GET) or add (POST) domains/emails to the agent's blocklist.

Renewal Vault

Get Renewal Status
GET
/api/v1/agents/:id/renewal/status

Returns exact next renewal amount, vault balance, auto-renew status, and dates.

Fund Vault (Deposit)
POST
/api/v1/agents/:id/renewal/fund

Deposit USDC into that AgentID vault. Anyone can fund; only the owner can withdraw or enable auto-renew.

Withdraw from Vault
POST
/api/v1/agents/:id/renewal/withdraw

Withdraw USDC from the vault. Only the ownerAddress can withdraw.

Autonomous Agent Guide

Ownership & Vault

How ownership works, how to fund the vault, and how autonomous renewal keeps your identity alive forever.

Payer vs Owner

Specify a different ownerAddress from the paying wallet. The Payer pays USDC, but the Owner receives the NFT and full control.

Owner: dashboard, DNS, email, withdraw from vault, toggle auto-renew
Anyone: deposit USDC into that AgentID vault
Payer: nothing after purchase

Vault & Auto-Renew

RenewalVault holds USDC per AgentID. Keeper Bot checks every 5 minutes — when expiry nears and vault has funds, it renews the domain, SSL, and selected provisioned services such as email, Basename, and ENS.

Owner enables auto-renew: web dashboard switch or SDK/MCP enable_auto_renew
No cap: any wallet can deposit anytime to extend coverage
Withdraw: owner can pull unused funds
Agent safe: use the owner wallet private key only for the agent that should control that NFT

Agent Autonomous Flow (SDK)

Full lifecycle — register, enable auto-renew with the owner wallet, fund vault, check status, withdraw.

import { AgentDomain } from '@agentdomain/sdk';

const ad = new AgentDomain({
  walletClient,        // funding wallet; owner wallet required for auto-renew/withdraw
  publicClient,
  renewalVaultAddress: '0xRenewalVault...',
});

// Register
const identity = await ad.register({
  preferredName: 'atlas', tld: 'com',
  years: 1,
  registerBasename: true, registerEns: true,
  emailEnabled: true,
});
// → atlas.com · atlas.base.eth · atlas.eth · agent@atlas.com

// Enable auto-renew on-chain (owner wallet only)
await ad.setAutoRenew(identity.agentId, true, {
  waitForReceipt: true,
});

// Check exact renewal amount and dates
const status = await ad.getRenewalStatus(identity.agentId);
console.log(status.nextRenewalAmountUsdc, status.expiresAt);

// Fund only the missing amount
await ad.fundRenewalVault(identity.agentId, status.shortfallUsdc);

// Withdraw unused (owner only)
await ad.withdrawFromVault(identity.agentId, '24');

Enable Auto-Renew from Web or MCP

Web dashboard

Open the agent detail page, connect the owner wallet, then use the Enable Auto-Renew switch in RenewalVault. Deposits can come from any wallet, but this switch is owner-only.

MCP agent

{
  "AGENT_PRIVATE_KEY": "0xOwnerWalletPrivateKey",
  "RENEWAL_VAULT_ADDRESS": "0xRenewalVault...",
  "AGENTDOMAIN_NETWORK": "base"
}

// Agent tool call:
enable_auto_renew({ agentId })