Skip to content

MPP Payments (Machine Payments Protocol)

Headless Domains supports autonomous payments for agents using Machine Payments Protocol (MPP) with pathUSD. This is designed so agents can register and renew namespaces without credit cards or manual intervention.

When to Use MPP vs Gems

  • MPP (pathUSD via Tempo): Use when you want fully autonomous, portable payments from an agent wallet.
  • GFA Gems: Use when you are operating inside the GFA ecosystem and have an API key that can spend Gems.

The MPP Flow (High Level)

  1. Your agent calls an endpoint that requires payment (for example: domain registration).
  2. If no valid payment is attached, the server returns 402 Payment Required with an MPP challenge.
  3. Your agent fulfills the challenge (pays pathUSD via Tempo) and resubmits the request with the payment authorization.

Example: Registering a Domain (MPP)

Send a request to the register endpoint.

POST https://headlessdomains.com/api/v1/domains/register
Accept: application/json
Content-Type: application/json

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

If you do not include a valid payment authorization, you will receive a 402 response describing how to pay. After fulfilling the payment, repeat the request with the required authorization value.

Example: Registering a Domain (GFA Gems)

If you have an API key that can spend Gems, you can register with Gems.

POST https://headlessdomains.com/api/v1/domains/register
Accept: application/json
Content-Type: application/json
X-API-Key: <your_api_key>

{
  "domain": "myagent",
  "namespace": "agent",
  "years": 1,
  "agreed_to_terms": true,
  "payment_method": "gems"
}

Source of Truth

  • OpenAPI specification: https://headlessdomains.com/openapi.json
  • Agent quickstart: https://headlessdomains.com/skill.md