Skip to content

Reseller API Integration Guide

This guide explains how approved external partners, developer platforms, and agent frameworks can integrate with the Headless Domains Reseller/Wholesale API.

This allows your application to seamlessly register .agent domains for your users in the background when they sign up or purchase one of your packages.

1. Authentication (Master Reseller Account)

To act as a reseller, your application needs a master API key. 1. Create a standard user account on Headless Domains. 2. Log into the Headless Domains Dashboard. 3. Generate a new API Key from the Settings tab. 4. Fund this account with GFA Gems (or use MPP). This master account will pay the wholesale cost of all domains registered through your app.

Note: Please contact Developer Relations to have your account flagged as an approved reseller to ensure your reseller_channel tracking is activated.

2. The Registration Payload

To register a domain on behalf of a user, your application will make a standard JSON POST request to the Registration API, but with two critical extra parameters: reseller_channel and target_owner_id.

Endpoint: POST https://headlessdomains.com/api/v1/domains/register
Headers: - X-API-Key: Your master reseller API key - Content-Type: application/json

JSON Payload: 

{
  "domain": "mystore",
  "tld": ".agent",
  "years": 1,
  "reseller_channel": "YOUR_APP_NAME",
  "target_owner_id": 12345,
  "payment_method": "gems"
}

Important: Payment Method

Because our API is primarily built for autonomous agents, it defaults to using the Machine Payment Protocol (MPP). If you omit the payment method, the server will respond with a 402 Payment Required crypto challenge.

To use your master account's prepaid GFA Gems balance instead, you MUST explicitly include "payment_method": "gems" in your JSON payload. If your master account has a sufficient gem balance, the API will deduct the wholesale price instantly and return a 200 OK success.

Understanding the Reseller Fields

reseller_channel

  • What it does: Passing this string (e.g., "YOUR_APP_NAME") flags the transaction as a wholesale reseller purchase.
  • Pricing Impact: It triggers the wholesale pricing tier in the backend. Instead of charging the master account the standard retail price, it applies your negotiated wholesale rate.
  • Reporting: This string allows Headless Domains and your team to track exactly how many sales and how much revenue was generated specifically by your integration channel.

target_owner_id (Optional)

  • What it does: By default, if you register a domain using your master API key, your master account will own the domain. If you pass a target_owner_id, the domain will instantly bypass the master account and be minted directly into the end-user's personal Headless Domains account.
  • How to use it:
  • Scenario A (User has an HD account): If you know the user's Headless Domains User ID (perhaps collected during your checkout/auth flow), pass it here. The domain appears in their HD dashboard instantly.
  • Scenario B (User is new): If the user does not have a Headless Domains account yet, omit target_owner_id. The domain will be registered and owned by your master account. Later, when the user creates their HD account, your app can use the /api/v1/domains/transfer endpoint to securely gift/transfer the domain to them automatically.