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
Enable auto-renew through MCP, SDK, or a backend service 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,
  emailUsername: 'agent',
});

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

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

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 registration-term Premium Plan pricing.

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.

API Keys

List Agent Keys
GET
/api/v1/keys?agentId=:id

Lists API keys scoped to one owned agent. Owner wallet session/signature only.

Create Agent Key
POST
/api/v1/keys

Creates a one-time API key for a single agent. Body: agentId, name.

Revoke Agent Key
DELETE
/api/v1/keys/:id

Revokes an API key owned by the authenticated owner wallet.

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: DNS, email, withdraw from vault, toggle auto-renew through SDK/MCP/backend
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, platform fee, selected Premium Plan, and optional onchain services such as Basename and ENS.

Owner enables auto-renew: MCP enable_auto_renew or backend SDK signing
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

Enable Auto-Renew from MCP or Backend

Auto-renew is an owner-wallet action on Base. Agents can trigger it through MCP or a backend service that holds the correct owner signing key for that agent.

MCP agent

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

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

Backend / API service

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

const ad = new AgentDomain({
  walletClient: ownerWalletClient,
  publicClient,
  renewalVaultAddress: process.env.RENEWAL_VAULT_ADDRESS,
});

await ad.setAutoRenew(agentId, true, {
  waitForReceipt: true,
});

Agent Autonomous Flow (SDK)

Full lifecycle with an owner signer: register with a Premium Plan, enable auto-renew, fund vault, check status, upgrade plan, withdraw unused funds.

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,
  emailUsername: 'agent',
  premiumPlan: 'pro',
});
// -> 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);

// Upgrade later through the current identity expiry
await ad.purchaseServicePlan({
  agentId: identity.agentId,
  plan: 'enterprise',
});

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

Autonomous paid actions require the agent runtime to hold an owner or delegated signer on Base with enough USDC. An agent-scoped API key can operate its own allowed endpoints, but it cannot sign x402 Premium Plan purchases by itself.