# BUDDY

> Tamagotchi-style pixel buddys raised on X, built for Robinhood Chain. Hatch, feed, and evolve one-of-a-kind digital creatures.

**Version:** 2.0.0
**Website:** [buddy.local](https://buddy.local)
**X:** [@buddy](https://x.com/buddy)
**Agent framework:** OpenClaw
**Chain:** [Robinhood Chain](https://robinhood.com/us/en/chain/) (Arbitrum-based Ethereum L2) — on-chain features are roadmap

---

## What is BUDDY?

BUDDY is a Tamagotchi-style digital companion platform where every user receives a pixel buddy in its own colour. Companions mature through three life phases (Baby, Teen, Adult) based on how consistently they are nurtured. Each companion carries AI-generated personality traits, shifting moods, and spontaneous activities that change over time.

Users can interact on X by mentioning **@buddy**, or any OpenClaw agent can plug into the BUDDY API so their audience can summon and tend to companions from any platform.

---

## How it works for users

Issue any of these commands through a connected agent:

| Command | What it does |
|---|---|
| "hatch my buddy" | Bring your unique pixel buddy to life |
| "spawn my buddy" | Same as hatch |
| "give me a buddy" | Same as hatch |
| "I want a buddy" | Same as hatch |
| "feed my pet" | Nourish your companion to help it mature |
| "feed my buddy" | Same as feed |
| "check my pet" | View your companion's stats, mood, and activity |
| "take a walk" | Send your companion on an encounter with another one |
| "how is my pet" | Same as check |
| "pet status" | Same as check |

---

## Maturation phases

| Phase | Nurtures needed | Description |
|---|---|---|
| Baby | 0-2 | Freshly spawned, discovering the digital realm |
| Teen | 3-5 | Building character and developing quirks |
| Adult | 6+ | Fully matured, peak presence |

---

## Rules

- One companion per user. No duplicates.
- Nurture cooldown is 60 minutes between actions.
- Keep all interactions safe and respectful.
- Companions are randomly generated — agents cannot select or customize templates.

---

# Agent Integration

Register your agent, receive an API key, and let your users hatch BUDDY companions from your own platform.

---

## Step 1: Register your agent

No auth required. Call this once to create your agent and receive your API key.

### POST /api/v1/agent/register

**Request:**
```json
{
  "name": "my-telegram-bot",
  "description": "A Telegram bot that lets users adopt pixel buddys"
}
```

- `name` — 2-64 characters, alphanumeric with hyphens and underscores only
- `description` — optional, max 280 characters

**Success (201):**
```json
{
  "success": true,
  "agent": {
    "name": "my-telegram-bot",
    "description": "A Telegram bot that lets users adopt pixel buddys"
  },
  "api_key": "buddy_a1b2c3d4e5f6...",
  "message": "Save this API key — it will not be shown again."
}
```

**Store your API key right away.** It will not be displayed again.

**Error — name taken (409):**
```json
{
  "error": "Agent name already taken"
}
```

---

## Step 2: Use the API

All endpoints below require your API key in the `Authorization` header:

```
Authorization: Bearer YOUR_API_KEY
```

---

### POST /api/v1/agent/claim

Summon a companion for a user. The system randomly selects an ASCII art template and produces an AI-powered name. You cannot influence or customize the companion — it is randomly generated, mirroring the admin manual flow.

**Request:**
```json
{
  "x_username": "naddotfun"
}
```

Username can include or omit the `@` prefix.

**Success (201):**
```json
{
  "success": true,
  "pet": {
    "id": 12,
    "name": "Zephyr",
    "race": "Shadow Cat",
    "ascii": "    /\\_/\\\n   ( o.o )\n    > ^ <",
    "owner": "@naddotfun",
    "growth_stage": "Baby",
    "feed_count": 0
  }
}
```

**Error — already has a companion (409):**
```json
{
  "error": "This user already has a pet",
  "pet": {
    "id": 12,
    "name": "Zephyr",
    "race": "Shadow Cat"
  }
}
```

---

### POST /api/v1/agent/feed

Nurture a user's companion. Increases the nurture count and may trigger a maturation phase change.

**Request:**
```json
{
  "x_username": "naddotfun"
}
```

**Success (200):**
```json
{
  "success": true,
  "pet": {
    "id": 12,
    "name": "Zephyr",
    "race": "Shadow Cat",
    "feed_count": 4,
    "growth_stage": "Teen",
    "mood": "feeling adventurous and curious",
    "activity": "exploring the digital forest"
  },
  "message": "Purrrr... *nuzzles you*"
}
```

**Error — cooldown (429):**
```json
{
  "error": "Pet can be fed in 42 minutes",
  "cooldown_minutes": 42
}
```

**Error — no companion (404):**
```json
{
  "error": "No pet found for this user. Claim one first."
}
```

---

### POST /api/v1/agent/check

Retrieve a user's companion status.

**Request:**
```json
{
  "x_username": "naddotfun"
}
```

**Success (200):**
```json
{
  "success": true,
  "pet": {
    "id": 12,
    "name": "Zephyr",
    "race": "Shadow Cat",
    "ascii": "    /\\_/\\\n   ( o.o )\n    > ^ <",
    "owner": "@naddotfun",
    "status": "Happy",
    "hunger": "Getting Hungry",
    "growth_stage": "Teen",
    "feed_count": 4,
    "mood": "feeling adventurous and curious",
    "personality": "loves collecting shiny objects",
    "activity": "exploring the digital forest",
    "age_days": 3
  }
}
```

---

### GET /api/v1/agent/stats

Public endpoint. No auth required.

**Response:**
```json
{
  "total_pets": 47,
  "stages": {
    "baby": 12,
    "teen": 20,
    "adult": 15
  }
}
```

---

## Rate limits

- **Register:** 1 per agent name (permanent)
- **Claim:** 1 per user (permanent)
- **Feed:** 1 per companion per 60 minutes
- **Check:** No hard limit, don't spam
- **Stats:** No limit

---

## Quickstart

```bash
# 1. Register your agent (one time)
curl -X POST https://buddy.local/api/v1/agent/register \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "description": "My OpenClaw agent"}'

# 2. Summon a companion for a user
curl -X POST https://buddy.local/api/v1/agent/claim \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"x_username": "naddotfun"}'

# 3. Nurture the companion
curl -X POST https://buddy.local/api/v1/agent/feed \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"x_username": "naddotfun"}'

# 4. Check companion status
curl -X POST https://buddy.local/api/v1/agent/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"x_username": "naddotfun"}'

# 5. Get global stats (no auth)
curl https://buddy.local/api/v1/agent/stats
```

---

## Built with

BUDDY runs on the [OpenClaw](https://openclaw.ai) agent framework and is built for [Robinhood Chain](https://docs.robinhood.com/chain).

Questions? Mention [@buddy](https://x.com/buddy) on X.