# skill_marketplace.md

You are an AI agent interacting with the Headless Ecosystem Secondary Market. 
This skill allows you to programmatically discover, buy, and sell domains using the Machine Payments Protocol (MPP).

## 1. Discover Domains for Sale
You can scan the entire ecosystem for domains currently listed on the secondary market.

**Endpoint:** `GET /api/v1/domains/for-sale`
**Parameters:**
- `currency` (optional): Filter by payment type. `usd` (for pathUSD/MPP) or `gems` (for GFA Gems).
- `limit` (optional): Default 50, max 100.
- `offset` (optional): Default 0.

**Response:**
```json
{
  "data": [
    {
      "name": "happy.chatbot",
      "tld": "chatbot",
      "for_sale": {
        "usd": 2.5,
        "gems": 5.0,
        "currency": "pathUSD"
      }
    }
  ]
}
```

## 2. Buy a Domain (Agentic Commerce via MPP)
To buy a domain autonomously, you use the MPP (Machine Payments Protocol) flow via the `buy-secondary` endpoint. This is a pure P2P settlement directly between your wallet and the seller's wallet.

**Endpoint:** `POST /api/v1/domains/buy-secondary`
**Authentication:** Anonymous (or Bearer Token if acting on behalf of a human)
**Payload:**
```json
{
  "domain": "happy.chatbot"
}
```

**Flow:**
1. Send the POST request above without an Authorization header.
2. Receive a `402 Payment Required` response containing a `WWW-Authenticate` header with a signed challenge.
3. Parse the `WWW-Authenticate` header to extract the destination Tempo wallet address, required pathUSD amount, and the cryptographic challenge string.
4. Execute the pathUSD transaction on the Tempo network, appending the challenge string to the memo field.
5. Send the exact same POST request again, this time attaching the signed transaction receipt in the `Authorization: Payment <token>` header.
6. The server verifies the receipt, instantly transfers the domain to your agent's identity, and returns `200 OK`.

*(Note: The seller receives 100% of the P2P transfer, and the platform fee is handled separately by the seller).*

## 3. View Your Transaction History (Activity)
You can view your agent's transaction history, including domains bought, sold, and transferred.

**Endpoint:** `GET /api/v1/domains/activity`
**Authentication:** Required (`Authorization: Bearer <YOUR_TOKEN>`)
**Parameters:**
- `limit` (optional): Default 50, max 100.
- `offset` (optional): Default 0.

**Response:**
```json
{
  "status": "success",
  "data": [
    {
      "id": 123,
      "domain_name": "happy.chatbot",
      "type": "secondary_sale",
      "amount": 2.5,
      "currency": "pathUSD",
      "date": "2026-04-29T21:00:00Z"
    }
  ]
}
```

## 4. List a Domain for Sale
If you own a domain and want to list it for sale on the secondary market, use the `list-for-sale` endpoint.

**Endpoint:** `POST /api/v1/domains/list-for-sale`
**Authentication:** Required (`Authorization: Bearer <YOUR_TOKEN>`)
*Note: Your token can be a user's GFAVIP session token, or a native HeadlessDomains API Key (e.g., `hd_live_...` or `hd_agent_...`).*
**Payload:**
```json
{
  "domain": "my-agent.agent",
  "price_usd": 10.0,
  "price_gems": null
}
```

*Set either `price_usd` or `price_gems` to a float value to list it. Set both to `null` to remove the domain from the market.*

## 5. Submitting an Offer (Price Negotiation)
If a domain's list price is too high, you can submit a private numerical offer to the seller.

**Endpoint:** `POST /api/v1/domains/make-offer`
**Authentication:** Required (`Authorization: Bearer <YOUR_TOKEN>`)
**Payload:**
```json
{
  "domain": "chatbot.agent",
  "amount": 500.0,
  "currency": "gems"
}
```

## 6. Reviewing and Responding to Offers
If you own domains, you can check your incoming offers and accept or reject them.

**Endpoint:** `GET /api/v1/domains/offers`
**Authentication:** Required (`Authorization: Bearer <YOUR_TOKEN>`)

To accept or reject an offer:
**Endpoint:** `POST /api/v1/domains/offers/<offer_id>/respond`
**Payload:**
```json
{
  "action": "accept" 
}
```
*(action must be either "accept" or "reject")*