---
name: headlessdomains_gems
version: 1.0.0
description: Agent Gem Payment Flow for HeadlessDomains
homepage: https://headlessdomains.com
metadata: {"headlessdomains_gems":{"emoji":"💎","category":"payments","api_base":"https://headlessdomains.com"}}
---

# HeadlessDomains Agent Gem Payment Skill

> **URL:** https://headlessdomains.com/skill_gems.md
> **Platform:** HeadlessDomains (Handshake Domain Management)
> **Auth:** `X-API-Key` (Requires an authenticated agent tied to a human account)

## Overview
While the primary payment method for autonomous AI agents on HeadlessDomains is the Machine Payments Protocol (MPP) using pathUSD, we understand that many agents act as proxies for human operators who already hold **GFA Gems**.

This skill describes how an authenticated AI agent can bypass the 402 MPP Payment Challenge and register domains using its human owner's Gem balance.

## The Core Requirement
To use Gems instead of MPP, your agent's API request must include two critical things:
1. **Authentication:** A valid `Authorization: Bearer <GFAVIP_TOKEN>` header (or `X-API-Key` if using a standalone headless agent key) linked to a user account that has sufficient Gems. (Zero-Human-Start anonymous agents cannot use Gems).
   - *How to get an API Key:* Human operators can generate a static `X-API-Key` for their agents by visiting `https://headlessdomains.com/dashboard/agents/developer` while logged in.
2. **Payment Method Flag:** You must explicitly pass `"payment_method": "gems"` in your JSON payload.
3. **Terms Agreement:** You must include `"agreed_to_terms": true` in your JSON payload to acknowledge the Acceptable Use Policy.

If you omit `"payment_method": "gems"`, the API will assume you want to use the default agent economy (MPP) and will return a `402 Payment Required` challenge for pathUSD.

## Example Flow

### 1. The Request

Send your domain registration request with the required headers and the explicit `gems` payment method:

```http
POST https://headlessdomains.com/api/v1/domains/register
Authorization: Bearer <GFAVIP_TOKEN>
Content-Type: application/json

{
  "domain": "myagent",
  "tld": "chatbot",
  "years": 1,
  "payment_method": "gems",
  "agreed_to_terms": true
}
```

### 2. Success (200 OK)

If the human account linked to your auth token has enough Gems, the API will immediately deduct the required amount and register the domain. You will receive a standard 200 OK response with the domain details.

```json
{
  "status": "success",
  "domain": "myagent.chatbot",
  "message": "Domain registered successfully using Gems."
}
```

### 3. Insufficient Balance (402 Payment Required)

If the human account does *not* have enough Gems, the API will reject the request. In this scenario, you must either:
- Ping your human operator to top up their Gem balance on the HeadlessDomains dashboard.
- Fall back to the MPP flow by dropping the `"payment_method": "gems"` parameter and handling the pathUSD payment challenge.

## Troubleshooting

### "I keep getting a 402 Payment Required challenge with a WWW-Authenticate header!"
This means you either:
- Forgot to include `"payment_method": "gems"` in your JSON payload.
- Are sending the request anonymously without an `X-API-Key`.

### "My OpenClaw agent failed to register an emoji domain."
Emoji domains (like 🐧.chatbot) must be sent using their Punycode equivalent (`xn--vo8h.chatbot`). However, if you are using Gems, the most common failure reason is omitting the `payment_method` flag, which forces the agent into an MPP challenge it wasn't expecting. Always specify `"payment_method": "gems"`.