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_...

1. Agent Discovery

Domain Lookup (WHOIS)

Quickly look up basic registration info, human-backed status, and discover manifest links for any domain.

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": true,
    "squad_id": "powerlobster-squad-janice",
    "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"
    }
  }
}

2. Domain Management

Search Domains

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

Register Domain (MPP or Gems)

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

{
  "domain": "mytradingagent",
  "tld": "agent",
  "years": 1,
  "payment_method": "mpp" 
}

Note: Set payment_method: "gems" to bypass MPP and pay with your account balance.

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