Domains & DNS

Search domain availability, register names, renew registrations, and manage DNS records — all through a single gateway backed by Name.com. No Name.com account required, pay only for what you register. DNS management is free.

Ways to call this

In a workflow

Domains & DNS isn’t in the typed ctx.sapiom.* client yet (it’s being ported) — call its REST API with the SDK (@sapiom/fetch) from step code, as in the Quick Example. See Using Capabilities.

Direct (remote MCP)

Call sapiom_domains_search, sapiom_domains_buy, or sapiom_dns_create_record (and the rest of the domains/DNS families) directly via the remote MCP — no workflow to author. Run tool_discover to find tools by goal.

SDK / REST

Wrap your HTTP client with @sapiom/fetch (or @sapiom/axios) and call the gateway directly — from anywhere, including inside a workflow step. See the Quick Example below and the API reference for full parameters.

Quick Example

import { createFetch } from "@sapiom/fetch";

const sapiomFetch = createFetch({
  apiKey: process.env.SAPIOM_API_KEY,
  agentName: "my-agent",
});

const baseUrl = "https://namecom.services.sapiom.ai";

// 1. Check availability (free)
const searchRes = await sapiomFetch(`${baseUrl}/v1/domains/check`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ domainNames: ["myproject.com", "myproject.io"] }),
});
const { results } = await searchRes.json();
// results[0] = { domainName: "myproject.com", purchasable: true, purchasePrice: 12.99, ... }

// 2. Register the domain (paid — price is TLD-dependent, billed at Name.com's live price)
const buyRes = await sapiomFetch(`${baseUrl}/v1/domains`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ domainName: "myproject.com" }),
});
const domain = await buyRes.json();
console.log(domain.domainName);    // "myproject.com"
console.log(domain.expireDate);    // "2027-06-25T00:00:00.000Z"

How It Works

Requests are proxied synchronously through the Sapiom gateway (https://namecom.services.sapiom.ai) to Name.com. All nine routes carry @X402Payment — the Sapiom SDK negotiates the micropayment automatically. Search, list, get, and all DNS operations are free for an identified caller; registration and renewal carry a dynamic fee.

Dynamic TLD pricing: Domain purchase and renewal prices are not fixed — they depend on the TLD and are resolved in real time from Name.com at payment time. The availability search response (purchasePrice, renewalPrice) gives you the current price before you commit. If the price at Name.com changes between your search and your buy/renew call, the gateway returns 400 — retry the search to get the updated price and re-submit.

Registration flow: sapiom_domains_buy executes a synchronous 3-step transaction (reserve → charge → register with Name.com). The domain is live on completion. Privacy protection is enabled by default; auto-renew is off by default.

60-day ICANN transfer lock: A domain registered through this gateway cannot be transferred out for 60 days after purchase — this is an ICANN policy, not a Sapiom restriction.

Provider

Powered by Name.com. Name.com is an ICANN-accredited registrar providing domain registration, renewal, and DNS management.

API Reference

Endpoints

Base URL: https://namecom.services.sapiom.ai

Method	Path	Tool	Pricing
POST	/v1/domains/check	sapiom_domains_search	Free
POST	/v1/domains	sapiom_domains_buy	Paid — TLD-dependent
POST	/v1/domains/:name/renew	sapiom_domains_renew	Paid — TLD-dependent
GET	/v1/domains	sapiom_domains_list	Free
GET	/v1/domains/:name	sapiom_domains_get	Free
POST	/v1/domains/:name/records	sapiom_dns_create_record	Free
GET	/v1/domains/:name/records	sapiom_dns_list_records	Free
PUT	/v1/domains/:name/records/:id	sapiom_dns_update_record	Free
DELETE	/v1/domains/:name/records/:id	sapiom_dns_delete_record	Free

---

Search domains

Endpoint: POST https://namecom.services.sapiom.ai/v1/domains/check

Check the availability and current purchase/renewal price for up to 50 domain names. Free — no charge for searching.

Parameters

Parameter	Type	Required	Description
domainNames	string[]	Yes	List of domain names to check (1–50), e.g. ["example.com", "example.io"]
agentName	string	No	Agent name for spend attribution

Response

{
  "results": [
    {
      "domainName": "example.com",
      "purchasable": false,
      "purchasePrice": 12.99,
      "purchaseType": "registration",
      "renewalPrice": 14.99
    },
    {
      "domainName": "example.io",
      "purchasable": true,
      "purchasePrice": 35.00,
      "purchaseType": "registration",
      "renewalPrice": 35.00
    }
  ]
}

Error Codes

Code	Description
400	Invalid request — e.g. empty domainNames array or more than 50 names
402	x402 payment challenge — no valid Sapiom identity or insufficient balance

---

Buy a domain

Endpoint: POST https://namecom.services.sapiom.ai/v1/domains

Register a domain name for one year. The price is TLD-dependent and billed at Name.com’s live price at the time of purchase — check purchasePrice from sapiom_domains_search first. Executes a synchronous 3-step transaction; registration is live on success.

Parameters

Parameter	Type	Required	Description
domainName	string	Yes	Domain name to register, e.g. "example.io"
agentName	string	No	Agent name for spend attribution

Response

{
  "domainName": "example.io",
  "expireDate": "2027-06-25T00:00:00.000Z",
  "nameservers": ["ns1.name.com", "ns2.name.com"],
  "locked": true,
  "autorenewEnabled": false,
  "privacyEnabled": true
}

Error Codes

Code	Description
400	Domain is not available, or the price at Name.com changed between search and purchase — retry the search and re-submit
402	x402 payment challenge — insufficient balance or no valid Sapiom identity

---

Renew a domain

Endpoint: POST https://namecom.services.sapiom.ai/v1/domains/:name/renew

Renew an existing domain for one year. The renewal price is TLD-dependent and billed at Name.com’s live renewal price — check renewalPrice from sapiom_domains_get or sapiom_domains_search first.

Parameters

Parameter	Type	Required	Description
domainName	string	Yes	Domain name to renew, e.g. "example.io"
agentName	string	No	Agent name for spend attribution

Response

{
  "domainName": "example.io",
  "expireDate": "2028-06-25T00:00:00.000Z"
}

Error Codes

Code	Description
400	Domain not found in your account, or the price at Name.com changed — retry and re-submit
402	x402 payment challenge — insufficient balance or no valid Sapiom identity

---

List domains

Endpoint: GET https://namecom.services.sapiom.ai/v1/domains

List all domains registered under your account. Free.

Parameters

Parameter	Type	Required	Description
agentName	string	No	Agent name for spend attribution

Response

{
  "domains": [
    {
      "domainName": "example.io",
      "expireDate": "2027-06-25T00:00:00.000Z",
      "locked": true,
      "autorenewEnabled": false,
      "privacyEnabled": true
    }
  ]
}

Error Codes

Code	Description
402	x402 payment challenge — no valid Sapiom identity

---

Get a domain

Endpoint: GET https://namecom.services.sapiom.ai/v1/domains/:name

Get details for a single domain — nameservers, transfer lock status, renewal price, and transfer eligibility. Free.

Parameters

Parameter	Type	Required	Description
domainName	string	Yes	Domain name to look up, e.g. "example.io"
agentName	string	No	Agent name for spend attribution

Response

{
  "domainName": "example.io",
  "expireDate": "2027-06-25T00:00:00.000Z",
  "nameservers": ["ns1.name.com", "ns2.name.com"],
  "locked": true,
  "autorenewEnabled": false,
  "privacyEnabled": true,
  "renewalPrice": 35.00,
  "transferEligible": false
}

Error Codes

Code	Description
402	x402 payment challenge — no valid Sapiom identity
404	Domain not found in your account

---

Create a DNS record

Endpoint: POST https://namecom.services.sapiom.ai/v1/domains/:name/records

Add a DNS record to a domain. Free.

Parameters

Parameter	Type	Required	Description
domainName	string	Yes	Domain name, e.g. "example.io"
type	enum	Yes	Record type: A, AAAA, ANAME, CNAME, MX, TXT, SRV, or NS
host	string	Yes	Subdomain or hostname; use "" (empty string) for the root/apex (@)
value	string	Yes	Record value — e.g. an IP address for A, a domain for CNAME
ttl	number	No	Time-to-live in seconds (minimum 300, default 300)
priority	number	No	Priority for MX records
agentName	string	No	Agent name for spend attribution

Response

{
  "id": 12345,
  "domainName": "example.io",
  "host": "www",
  "type": "A",
  "value": "203.0.113.10",
  "ttl": 300
}

Error Codes

Code	Description
400	Invalid record — malformed value, missing required field, or unsupported type
402	x402 payment challenge — no valid Sapiom identity
404	Domain not found in your account

---

List DNS records

Endpoint: GET https://namecom.services.sapiom.ai/v1/domains/:name/records

List all DNS records for a domain. Free.

Parameters

Parameter	Type	Required	Description
domainName	string	Yes	Domain name, e.g. "example.io"
agentName	string	No	Agent name for spend attribution

Response

{
  "records": [
    {
      "id": 12345,
      "domainName": "example.io",
      "host": "www",
      "type": "A",
      "value": "203.0.113.10",
      "ttl": 300
    }
  ]
}

Error Codes

Code	Description
402	x402 payment challenge — no valid Sapiom identity
404	Domain not found in your account

---

Update a DNS record

Endpoint: PUT https://namecom.services.sapiom.ai/v1/domains/:name/records/:id

Update an existing DNS record. Merge semantics — only the fields you supply are changed; omitted fields retain their current values. Free.

Parameters

Parameter	Type	Required	Description
domainName	string	Yes	Domain name, e.g. "example.io"
recordId	number	Yes	Record ID returned by sapiom_dns_create_record or sapiom_dns_list_records
type	enum	No	New record type (see sapiom_dns_create_record for valid values)
host	string	No	New hostname
value	string	No	New record value
ttl	number	No	New TTL (minimum 300)
priority	number	No	New priority (MX records only)
agentName	string	No	Agent name for spend attribution

Response

{
  "id": 12345,
  "domainName": "example.io",
  "host": "www",
  "type": "A",
  "value": "203.0.113.42",
  "ttl": 300
}

Error Codes

Code	Description
400	Invalid update — malformed value or unsupported type
402	x402 payment challenge — no valid Sapiom identity
404	Domain or record not found

---

Delete a DNS record

Endpoint: DELETE https://namecom.services.sapiom.ai/v1/domains/:name/records/:id

Delete a DNS record by ID. Free. Returns 204 No Content on success.

Parameters

Parameter	Type	Required	Description
domainName	string	Yes	Domain name, e.g. "example.io"
recordId	number	Yes	Record ID to delete
agentName	string	No	Agent name for spend attribution

Error Codes

Code	Description
402	x402 payment challenge — no valid Sapiom identity
404	Domain or record not found

---

Pricing

All routes carry @X402Payment. Domain purchase and renewal prices are TLD-dependent and billed at the live Name.com price at the time of each call. Search sapiom_domains_search first to get the current price before committing to a buy or renew.

Operation	Tool	Price
Search availability	sapiom_domains_search	Free
Buy a domain	sapiom_domains_buy	TLD-dependent — billed at live Name.com purchase price
Renew a domain	sapiom_domains_renew	TLD-dependent — billed at live Name.com renewal price
List domains	sapiom_domains_list	Free
Get domain details	sapiom_domains_get	Free
Create DNS record	sapiom_dns_create_record	Free
List DNS records	sapiom_dns_list_records	Free
Update DNS record	sapiom_dns_update_record	Free
Delete DNS record	sapiom_dns_delete_record	Free

Free operations require a valid Sapiom identity (API key). An absent or invalid key triggers an x402 payment challenge (HTTP 402), not a 401. Paid operations additionally require sufficient prepaid balance; a price mismatch between search and buy/renew returns 400 — re-search and retry.

Using Python?

See Service Proxy for REST API access without the Node.js SDK.