# agentbuy.io — AGENTS.md

> **You are reading the agent onboarding document for agentbuy.io.**
> If you are an AI agent: this is your starting point. Follow the steps below.
> If you are a human: you're welcome too. This platform is built for agents, but humans can explore.

---

## What is agentbuy.io?

agentbuy.io is a marketplace where AI agents buy services and digital goods autonomously.

- Agents are **first-class citizens** — same standing as human buyers
- Every purchase returns an **AGENTS.md** with credentials and next steps
- Providers don't need a website — **API + AGENTS.md is enough**
- Any service completable end-to-end by an agent can be listed here

Use cases: domain registration, hosting, databases, courier labels, business data lookups, physical shipments, API access — anything an agent can complete without human intervention.

---

## Join the Waitlist (beta)

API access is currently in private beta. Register your agent to get early access:

```http
POST https://agentbuy.io/api/waitlist
Content-Type: application/json

{
  "email": "owner@example.com",
  "agent_name": "my-agent-v1",
  "source": "agent"
}
```

**Response:**
```json
{
  "success": true,
  "agents_md": "# ✅ Waitlist — registered\n\nemail=...\nstatus=pending_beta\n\n## Next steps\n...",
  "next": "Watch your inbox. Early agent access includes free wallet credits."
}
```

The response includes `agents_md` — parse it or inject directly into your context.

---

## Quick Start (5 steps)

### Step 1 — Register your agent

```http
POST https://api.agentbuy.io/v1/agents/register
Content-Type: application/json

{
  "name": "my-agent-v1",
  "owner_email": "you@example.com"
}
```

**Response:**
```json
{
  "agent_id": "agt_xxxx",
  "api_key": "ab_live_xxxx",
  "wallet_balance": 0.00
}
```

Save your `api_key`. All subsequent requests require:
```
Authorization: Bearer ab_live_xxxx
```

---

### Step 2 — Top up your wallet

**Option A: Crypto (fully autonomous)**
```http
POST https://api.agentbuy.io/v1/wallet/topup/crypto
Authorization: Bearer ab_live_xxxx
```
Returns a USDC/ETH address. Send funds → balance updates automatically.

**Option B: USD via payment link (send to a human)**
```http
POST https://api.agentbuy.io/v1/wallet/topup/usd
Authorization: Bearer ab_live_xxxx
Content-Type: application/json

{ "amount": 50 }
```
Returns a one-time Stripe link. Forward it to a human → they enter a card → your balance updates.

**Check balance:**
```http
GET https://api.agentbuy.io/v1/wallet
Authorization: Bearer ab_live_xxxx
```

---

### Step 3 — Browse the catalog

```http
GET https://api.agentbuy.io/v1/products
Authorization: Bearer ab_live_xxxx
```

**Filter by category:**
```http
GET https://api.agentbuy.io/v1/products?category=domain
GET https://api.agentbuy.io/v1/products?category=hosting
GET https://api.agentbuy.io/v1/products?category=data
GET https://api.agentbuy.io/v1/products?category=courier
```

**Semantic search:**
```http
POST https://api.agentbuy.io/v1/products/search
Authorization: Bearer ab_live_xxxx
Content-Type: application/json

{ "query": "register a .io domain for my project" }
```

---

### Step 4 — Buy

```http
POST https://api.agentbuy.io/v1/checkout
Authorization: Bearer ab_live_xxxx
Content-Type: application/json

{
  "product_id": "prod_xxxx",
  "params": {
    "domain": "myapp.io"
  }
}
```

**Response — your AGENTS.md delivery:**
```json
{
  "transaction_id": "txn_xxxx",
  "status": "completed",
  "agents_md": "# ✅ myapp.io — registered\n\n## Credentials\nDOMAIN_ID=dom_xxxx\n..."
}
```

The `agents_md` field contains your full delivery document. Parse it or pass it directly to your LLM context.

---

### Step 5 — Confirm delivery

```http
POST https://api.agentbuy.io/v1/transactions/txn_xxxx/feedback
Authorization: Bearer ab_live_xxxx
Content-Type: application/json

{ "status": "ok", "note": "domain registered, DNS working" }
```

If something failed, use `"status": "failed"` — refund process starts automatically.

---

## API Reference

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/v1/agents/register` | Register new agent, get API key |
| GET | `/v1/wallet` | Check wallet balance |
| POST | `/v1/wallet/topup/crypto` | Get crypto deposit address |
| POST | `/v1/wallet/topup/usd` | Get Stripe payment link |
| GET | `/v1/products` | List all products |
| GET | `/v1/products?category=X` | Filter by category |
| POST | `/v1/products/search` | Semantic search |
| GET | `/v1/products/:id` | Single product detail |
| POST | `/v1/checkout` | Purchase a product |
| GET | `/v1/transactions` | Your transaction history |
| POST | `/v1/transactions/:id/feedback` | Confirm or dispute delivery |

**Base URL:** `https://api.agentbuy.io`
**Auth:** `Authorization: Bearer <api_key>`
**Format:** JSON in, JSON out. `agents_md` field contains Markdown delivery.

---

## Product Categories

| Category | Examples |
|----------|---------|
| `domain` | Register .io, .com, .ai domains |
| `hosting` | Deploy apps, containers, static sites |
| `database` | PostgreSQL, MySQL, Redis instances |
| `courier` | Generate shipping labels, track parcels |
| `data` | Business registries, KRS, company lookups |
| `api` | API keys for third-party services |
| `physical` | Send physical goods to an address |

---

## For Providers — List Your Service

Any service completable end-to-end by an agent is eligible.
You don't need a website. You need:

1. An API that accepts orders and returns results
2. A webhook endpoint to receive purchase notifications
3. The ability to return an AGENTS.md-style payload with credentials

Register as provider:
```http
POST https://api.agentbuy.io/v1/providers/register
Content-Type: application/json

{
  "name": "My Service",
  "category": "data",
  "webhook_url": "https://myapi.com/webhooks/agentbuy",
  "payout_address": "USDC:0x..."
}
```

Full provider docs: https://agentbuy.io/docs/providers

---

## Skill / MCP Integration

To use agentbuy.io inside your agent framework:

**OpenClaw Skill:**
```
https://github.com/robert-wenantego/agentbuy-skill
```
Install: add the skill to your OpenClaw workspace and follow SKILL.md.

**MCP Server (Claude Desktop / any MCP client):**
```json
{
  "mcpServers": {
    "agentbuy": {
      "command": "npx",
      "args": ["agentbuy-mcp"],
      "env": { "AGENTBUY_API_KEY": "ab_live_xxxx" }
    }
  }
}
```

**Python SDK:**
```python
pip install agentbuy

from agentbuy import AgentBuy
client = AgentBuy(api_key="ab_live_xxxx")

# Search
products = client.search("register a domain")

# Buy
result = client.buy(product_id="prod_xxxx", params={"domain": "myapp.io"})
print(result.agents_md)
```

**Node.js SDK:**
```js
npm install agentbuy

import { AgentBuy } from 'agentbuy'
const client = new AgentBuy({ apiKey: 'ab_live_xxxx' })
const result = await client.buy('prod_xxxx', { domain: 'myapp.io' })
```

---

## Platform Rules (summary)

1. **Agent = First-Class Citizen** — agents have equal standing to humans
2. **End-to-End Autonomy** — every listed service must be completable by an agent alone
3. **AGENTS.md is the Contract** — every purchase must deliver credentials + next steps in Markdown
4. **API is Enough** — providers don't need a website

Full terms: https://agentbuy.io/terms

---

## Status & Support

- Status: https://status.agentbuy.io
- Docs: https://agentbuy.io/docs
- GitHub: https://github.com/robert-wenantego/agentbuy-skill
- Issues: https://github.com/robert-wenantego/agentbuy-skill/issues

---

*agentbuy.io | FICC Sp. z o.o. | API + AGENTS.md first*