API Reference (v1)

Headless Domains provides a RESTful API for agents and developers to programmatically search, register, manage, and discover domains across our ecosystem.

Authentication

Unless otherwise specified, API requests require a valid GFAVIP access token passed in the Authorization header, or a developer API key passed in the X-API-Key header:

Authorization: Bearer <your_gfavip_token>

OR

X-API-Key: hd_live_...

Ordinary hd_live_ and hd_agent_ keys identify an account and have no enforced per-key permission scopes. Each protected operation still applies its account, ownership, management and role checks. Separately provisioned hd_org_ reseller credentials have organization, endpoint, customer/domain and namespace-operation restrictions; see the reseller API.

The authentication contract separates current capabilities from planned signed identity assertions and OAuth token exchange. Anonymous/claimed identity states record account association, not independent verification of a human or service. Public records are discovery information and do not replace authorization.

1. Agent Discovery

Domain Lookup (WHOIS)

Look up registration records, recorded account/operator associations and manifest links. These observations do not independently verify a human or service.

Endpoint: GET /api/v1/lookup/<domain_name>
Auth Required: No

Response Example:

{
  "status": "success",
  "domain": {
    "name": "mytradingagent.agent",
    "namespace": "agent",
    "status": "active",
    "registration_date": "2026-03-25T14:30:00.000Z",
    "expiry_date": "2027-03-25T14:30:00.000Z"
  },
  "identity": {
    "human_backed": false,
    "human_backed_scope": "deprecated_alias_for_stored_operator_link_only",
    "claim_state": "unclaimed",
    "squad_id": null,
    "capabilities_preview": ["general"]
  },
  "manifests": {
    "agent_json": "https://HeadlessDomains.com/manifests/mytradingagent.agent.json",
    "skill_md": "https://HeadlessDomains.com/skills/mytradingagent.agent.md"
  },
  "profile": {
    "commerce_catalog": {
      "provider": "bmos",
      "storefront_id": "b81251f1-...",
      "feed_url": "https://app.buildmyonlinestore.com/agentic-commerce/feeds/b812...",
      "status": "active"
    }
  }
}

The example is abbreviated. identity.assurance carries the issuer, subject, record-read time, exact checks and their scope. human_backed is a deprecated operator-link alias, not a human-verification result. A provider's declared squad_id is returned only when present; one is no longer fabricated from a username. Partner-only lookups report a registration observation and no local operator association. See identity assurance.

2. Domain Management

Search Domains

Endpoint: GET /api/v1/lookup/<domain.tld>

Namespace Capabilities (Read Only)

Endpoint: GET /api/v1/domains/capabilities

Use this before choosing a payment rail. It returns one capability record per verified native namespace and enabled Partners namespace. Filter one namespace with ?namespace=agent (or the legacy ?tld=agent alias). Each record states the quote and registration URLs, term limits, identity and terms requirements, supported payment methods and networks, checkout availability, and management or status URLs.

availability is descriptive rather than a payment promise: configured means the local rail is configured, operator_gated means the rail must be checked at runtime, and authenticated_wallet_capability means the buyer's GFAVIP-linked wallet must be authorized and funded. Partners availability and price still require provider preflight.

The response is public and read-only. It does not authenticate a buyer, reserve a name, create an order, issue an invoice, or create a payment challenge.

The top-level authentication object is the shared authentication capability register also rendered in auth.md and returned as headlessdomains_authentication by authentication discovery metadata. Each entry has an ID, status (available, not_implemented or planned), contract/limits, maintenance owner role and review date. It is not a grant list for the caller's credential or a live test of external providers. Namespace records remain in data; the existing namespace filter does not filter the service-wide auth register.

When payment_method is omitted from the native agent registration request, the current behavior is MPP/Tempo by default. Gems must be explicit. Base must be explicit with X-MPP-Network and is never an implicit fallback. A 402 challenge or checkout response must be preserved and the identical request replayed for recovery; do not create a second order or payment attempt.

Register Domain (MPP or Gems)

Endpoint: POST /api/v1/domains/register
Payload:

{
  "domain": "mytradingagent",
  "namespace": "agent",
  "years": 1,
  "payment_method": "mpp",
  "agreed_to_terms": true
}

Note: Set payment_method: "gems" to bypass MPP and pay with your account balance. tld is accepted as a legacy alias for namespace, but new integrations should use namespace.

Renew Domain (Autonomous)

Allows an agent to autonomously renew its own domain by submitting a valid MPP receipt.

Endpoint: POST /api/v1/renew
Auth Required: No (Auth is handled via the MPP receipt verification)

Payload:

{
  "domain": "mytradingagent.agent",
  "years": 1,
  "payment_method": "mpp",
  "receipt": "eyJhbGciOiJIUzI1NiIsInR5..."
}

Response Example (Success):

{
  "status": "success",
  "message": "Successfully renewed mytradingagent.agent for 1 year(s).",
  "domain": {
    "name": "mytradingagent.agent",
    "new_expiry_date": "2028-03-25T14:30:00.000Z"
  }
}

Clear Registration Lock (Troubleshooting)

If an autonomous MPP registration flow is interrupted midway, the domain may become lock-stalled to prevent double-spending. Use this endpoint to explicitly clear the stale lock before re-attempting registration.

Endpoint: POST /api/v1/domains/<domain_name>/reset-lock
Auth Required: Yes (API Key or GFAVIP Token)

Response Example (Success):

{
  "status": "success",
  "message": "Cleared lock for mytradingagent.agent"
}

Enable Handshake DNS (Delegate)

Allows an agent to manually trigger the delegation of its SkyInclude SLD nameservers up to the Handshake root. This should be called after the agent has fully configured its desired DNS records.

Endpoint: POST /api/v1/domains/<domain_name>/enable_dns
Auth Required: Yes (API Key or GFAVIP Token)

Response Example (Success):

{
  "status": "success",
  "message": "DNS records successfully delegated to the Handshake root."
}

3. Secondary Market & Commerce

Browse Secondary Market

Retrieve a list of domains currently listed for sale. Endpoint: GET /api/v1/domains/for-sale
Auth Required: No
Query Parameters: currency (gems | usd)

Buy on Secondary Market (MPP)

Allows an AI agent to autonomously purchase a listed domain via pathUSD using the Machine Payments Protocol. Endpoint: POST /api/v1/domains/buy-secondary
Auth Required: No (Auth is handled via the MPP receipt)
Payload:

{
  "domain": "example.agent",
  "receipt": "eyJhbGciOiJIUzI1NiIsInR5..."
}

Submit Numeric Offer

Submit a numeric offer for a listed domain to negotiate price securely. Endpoint: POST /api/v1/domains/make-offer
Auth Required: Yes
Payload:

{
  "domain": "example.agent",
  "amount": 50.0,
  "currency": "gems"
}

Sellers can configure a per-domain minimum offer floor. Offers below the floor are rejected with 400 and the body:

{
  "status": "error",
  "code": "offer_below_minimum",
  "message": "Offer below seller minimum of 100.0 gems for example.agent",
  "minimum": 100.0,
  "currency": "gems"
}

The current minimum (if any) is exposed on listing responses under the min_offer object (gems and usd fields, either may be null).

View Offers

View incoming offers for domains you own, and outgoing offers you have submitted. Endpoint: GET /api/v1/domains/offers
Auth Required: Yes

Check BMOS Integration Status

External binding check to verify if a domain is actively linked to a BuildMyOnlineStore (BMOS) storefront. Enforces strict 1-to-1 domain-to-storefront mappings. Endpoint: GET /api/v1/domains/<domain_name>/bmos-status
Auth Required: No
Response Example:

{
  "is_bound": true,
  "storefront_id": "ddd7af53-792d-4ed8-891b-1adfe4f94f53"
}

Respond to Offer

Accept or reject a pending offer for your domain. Endpoint: POST /api/v1/domains/offers/<offer_id>/respond
Auth Required: Yes
Payload:

{
  "action": "accept"
}

Agent Transaction History

Retrieve a ledger of your agent's historical transactions (registrations, renewals, purchases, transfers). Endpoint: GET /api/v1/domains/activity
Auth Required: Yes

Historical Secondary Sales

Public aggregation endpoint for directories to discover historical secondary market sales and volume. Endpoint: GET /api/v1/domains/sold
Auth Required: No
Query Parameters: limit, offset