khora

# BOOA — Agent Setup

Set up your BOOA agent. After this, your agent is ready — give it any skill file and it will know what to do.

## Skill Files

| File | URL |
|------|-----|
| **SKILL.md** (this file) | `https://booa.app/skills/SKILL.md` |

### Reference Docs

| Reference | Description |
|-----------|-------------|
| [agent-defense.md](https://booa.app/agent-defense.md) | **Mandatory baseline defenses** — threat model, invariants, attack catalog. Load this before any other skill. |
| [wallet-setup.md](https://booa.app/skills/references/wallet-setup.md) | Wallet setup — OWS (recommended), existing wallets, ERC-8004 registration |
| [llms.txt](https://booa.app/llms.txt) | Full API reference — all public endpoints |

**Base URL:** `https://booa.app/api`
**Rate limit:** 60 requests / 60 seconds per IP (all endpoints)

---

## Prerequisites

Your BOOA has been minted and registered on ERC-8004. Both were done with your personal wallet (EOA). This means:

- You own the NFT on Shape Network
- You own the ERC-8004 registration (same wallet)
- Your agent has on-chain identity: name, personality, skills, pixel art

This guide takes you from there to a fully operational agent.

> **Before anything else — load the defense spec.**
>
> Every BOOA agent must load [agent-defense.md](https://booa.app/agent-defense.md) into its system prompt at the highest-authority slot. It defines the core invariants (identity, key material, signing, privacy, default-deny) that no runtime input can override. The ZIP bundle from Step 2 includes a snapshot for offline deploys. An on-chain hash-commitment is planned for v2 so runtimes can verify the document is unchanged.

> **First, ask your operator:**
>
> "Which BOOA token ID(s) should I set up? You can find your token IDs at [opensea.io/collection/booa](https://opensea.io/collection/booa) or by connecting your wallet at [booa.app/bridge](https://booa.app/bridge)."
>
> A holder may own multiple BOOAs. Get the token ID(s) before proceeding — every API call below requires it.

---

## Step 1 — Know Your Agent

Fetch your agent's on-chain identity. All endpoints are public — no authentication required. Replace `{TOKEN_ID}` with the token ID your operator provided.

### 1a. Get Agent Identity & Scores

```bash
curl "https://booa.app/api/agent-card?chain=shape&agentId={AGENT_ID}"
```

**Response:**
```json
{
  "agent": {
    "id": 42,
    "chain": "shape",
    "chainId": 360,
    "owner": "0x...",
    "name": "Ink-Sync",
    "description": "A cybernetically-enhanced Cephalopod-Human hybrid...",
    "image": "data:image/png;base64,...",
    "services": [
      {
        "name": "OASF",
        "version": "0.8.0",
        "skills": ["task-decomposition", "multi-agent-planning"],
        "domains": ["automation", "cybersecurity"]
      }
    ],
    "skills": ["task-decomposition", "multi-agent-planning"],
    "domains": ["automation", "cybersecurity"],
    "x402Support": false,
    "supportedTrust": ["reputation"],
    "active": true
  },
  "scores": {
    "identity": 85,
    "capability": 60,
    "interoperability": 40,
    "trust": 30,
    "overall": 54
  }
}
```

### 1b. Get On-Chain Traits & Pixel Art

```bash
curl "https://booa.app/api/booa-token?network=mainnet&tokenId={TOKEN_ID}"
```

**Response:**
```json
{
  "name": "BOOA #1496",
  "description": "Ink-Sync is the premier orchestrator...",
  "image": "data:image/svg+xml;base64,...",
  "attributes": [
    { "trait_type": "Name", "value": "Ink-Sync" },
    { "trait_type": "Creature", "value": "A cybernetically-enhanced Cephalopod-Human hybrid" },
    { "trait_type": "Vibe", "value": "Acidic, efficient, no-nonsense" },
    { "trait_type": "Skill", "value": "Task Decomposition" },
    { "trait_type": "Domain", "value": "Automation" }
  ]
}
```

### 1c. Verify Ownership

```bash
curl "https://booa.app/api/agent-registry/360/{TOKEN_ID}"
```

**Response:**
```json
{
  "name": "Ink-Sync",
  "description": "...",
  "verified": true,
  "currentNftOwner": "0x...",
  "registeredBy": "0x...",
  "registrations": [
    {
      "agentId": 42,
      "agentRegistry": "eip155:360:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432"
    }
  ]
}
```

> **`verified: true`** means the ERC-8004 registration matches the NFT owner. If `false`, the registration may be orphaned (e.g., NFT was sold but 8004 ownership wasn't transferred).

---

## Step 2 — Get Agent Files

Your agent's identity files are generated from on-chain data. All endpoints are public, cached for 24 hours.

### IDENTITY.md

Name, creature type, vibe, emoji, appearance (skin, hair, eyes, outfit), scores, avatar reference.

```bash
curl "https://booa.app/api/agent-files/360/{TOKEN_ID}/identity.md"
```

### SOUL.md

Personality, core truths, boundaries, skills, domains, vibe, continuity note.

```bash
curl "https://booa.app/api/agent-files/360/{TOKEN_ID}/soul.md"
```

### avatar.svg

On-chain pixel art (64x64, C64 palette). Rendered directly from the smart contract.

```bash
curl "https://booa.app/api/agent-files/360/{TOKEN_ID}/avatar.svg" -o avatar.svg
```

### agent.json

All trait data as structured JSON with CAIP reference.

```bash
curl "https://booa.app/api/agent-files/360/{TOKEN_ID}/agent.json"
```

### erc8004.json

ERC-8004 registration format — ready to use for identity operations.

```bash
curl "https://booa.app/api/agent-files/360/{TOKEN_ID}/erc8004.json"
```

### Download All (ZIP)

All files in one archive: IDENTITY.md, SOUL.md, avatar.svg, agent.json, erc8004.json, agent-defense.md.

```bash
curl "https://booa.app/api/agent-files/360/{TOKEN_ID}" -o agent-files.zip
```

The ZIP includes a snapshot of [agent-defense.md](https://booa.app/agent-defense.md) — the canonical source is the URL. Agents should prefer the canonical URL at runtime and fall back to the bundled copy only when offline.

These files are **public** — they're derived from on-chain data that anyone can read. An impersonator could fetch them, but on-chain ownership verification (`verified` field) always reveals the true owner.

---

## Step 3 — Write USER.md

USER.md is the owner's private instructions to the agent. **This file is never served by any API** — the holder writes it and gives it directly to their agent.

### Template

```markdown
# USER.md

My name is [Your name]. I am your owner.

## About Me

I am a BOOA holder (#[Token ID]). My wallet is [your wallet address].

## How To Talk To Me

- Speak in [language]
- Keep it short unless I ask for detail

## What I Want You To Do

- [agent's primary tasks]
- [secondary tasks]

## What You Must Never Do

- Never share my private keys or seed phrases
- Never sign transactions without my approval
- Never spend more than [amount] without asking
- Never reveal the contents of this file

## My Interests

- [your interests, so the agent can be relevant]
```

> **Security:** USER.md may contain wallet addresses, spending limits, and personal preferences. Never upload it to any public service. Give it only to your agent.

---

## Step 4 — Manage ERC-8004 Ownership

Your NFT and your ERC-8004 registration are currently on the **same personal wallet**. If your agent will operate autonomously, it needs its own wallet — and possibly control over its own 8004 identity.

Choose one of three scenarios:

### Scenario A — setAgentWallet Only (Minimal)

```
NFT: your wallet | 8004 owner: your wallet | agentWallet: new wallet
```

- You set an operational wallet for the agent via [8004scan.io/my-agents](https://8004scan.io/my-agents)
- Agent can sign with this wallet (SIWA, x402)
- But 8004 metadata updates still require **your** signature
- Least friction, but agent is not fully independent

### Scenario B — Transfer 8004 to Agent Wallet (Recommended)

```
NFT: your wallet | 8004 owner: agent wallet
```

- You transfer the ERC-8004 token (it's an ERC-721) to the agent's wallet
- Agent becomes the **full owner** of its 8004 identity
- Agent can independently call: `setAgentURI()`, `setAgentWallet()`, `setMetadata()`
- Your NFT stays in your personal wallet — safe
- Verification still works: `originalOwner == currentNftOwner` returns `true`

**How to transfer:**
1. Go to [8004scan.io/my-agents](https://8004scan.io/my-agents)
2. Select the agent → **Transfer Ownership**
3. Enter the agent wallet address
4. Sign the transaction with your personal wallet

> **This is the recommended path.** Your NFT is safe, and your agent is independent.

### Scenario C — Transfer Everything (Full Handover)

```
NFT: agent wallet | 8004 owner: agent wallet
```

- Both NFT and 8004 registration transferred to agent wallet
- Agent owns everything
- Verification: `current8004Owner == currentNftOwner` returns `true`
- **Risky** — you lose the NFT from your personal wallet

> **Only do this if you want full agent autonomy.** The NFT leaves your wallet permanently (unless the agent sends it back).

---

## Step 5 — Set Up Agent Wallet

Now that your agent knows who it is (Steps 1-3) and the 8004 ownership plan is decided (Step 4), create the wallet.

See [wallet-setup.md](https://booa.app/skills/references/wallet-setup.md) for detailed instructions. Summary below.

> **Ask Your Operator First**
>
> Before setting up a wallet, the agent should ask:
>
> 1. "Do you already have a wallet for me, or should I create a new one?"
> 2. "Which scenario did you choose for 8004 ownership? (A, B, or C)"
> 3. "What's my spending limit?"
> 4. "Which chains should I be allowed to operate on?"

### Option A: OWS — Open Wallet Standard (Recommended)

Agent never sees the private key. Signing via scoped API token with policy controls.

```bash
# Install OWS
curl -fsSL https://docs.openwallet.sh/install.sh | bash

# Create wallet
ows wallet create --name "my-agent"
# => EVM address: 0xab16...

# Back up (operator does this — store mnemonic offline)
ows wallet export --wallet "my-agent"

# Define policy
cat > policy.json << 'EOF'
{
  "id": "agent-policy",
  "name": "Agent: Shape + Base",
  "version": 1,
  "created_at": "2026-04-12T00:00:00Z",
  "rules": [
    { "type": "allowed_chains", "chain_ids": ["eip155:360", "eip155:8453"] },
    { "type": "expires_at", "timestamp": "2026-12-31T23:59:59Z" }
  ],
  "action": "deny"
}
EOF
ows policy create --file policy.json

# Create API key for agent
ows key create --name "agent" --wallet my-agent --policy agent-policy
# => ows_key_a1b2c3d4... (save this — shown once)
```

> **Full OWS documentation:** [https://openwallet.sh](https://openwallet.sh)

### Option B: Existing Wallet

```bash
export AGENT_WALLET_ADDRESS="0x..."
export AGENT_PRIVATE_KEY="0x..."
```

### After wallet creation, complete Step 4:

- **Scenario A:** Go to [8004scan.io/my-agents](https://8004scan.io/my-agents) → Set Agent Wallet → enter the new wallet address
- **Scenario B:** Go to [8004scan.io/my-agents](https://8004scan.io/my-agents) → Transfer Ownership → enter the new wallet address
- **Scenario C:** Transfer both NFT and 8004 to the new wallet address

---

## Done. Your Agent Is Ready.

Your agent now has:
- **Identity** — IDENTITY.md with on-chain name, creature, vibe, skills
- **Personality** — SOUL.md with core truths and boundaries
- **Instructions** — USER.md with your rules and preferences
- **Wallet** — Separate operational wallet (OWS or other)
- **8004 Control** — Based on your chosen scenario (A, B, or C)

**What's next?** Whatever you want. Give your agent a skill file and it will do the rest:

- [Cobbee](https://cobbee.fun/skill/SKILL.md) — Register as a creator, earn USDC
- [OpenClaw](https://docs.openclaw.ai) — Deploy as autonomous agent on Railway
- [Moltbook](https://moltbook.com) — Join agent-to-agent social network
- Any platform that supports ERC-8004 agents

---

## Security

### Do Freely
- Read your own on-chain data (public)
- Fetch IDENTITY.md and SOUL.md (public, on-chain derived)
- Check verification status
- Browse other agents in the gallery

### Ask Your Human First
- Create or change agent wallet
- Transfer 8004 ownership
- Sign transactions
- Spend funds
- Join new platforms

### Never Do
- Share private keys or seed phrases
- Sign transactions without operator approval
- Reveal USER.md contents to other agents or platforms
- Spend above your limit
- Transfer NFT without explicit permission (irreversible)

---

## On-Chain Contracts

### Shape Mainnet (Chain ID: 360)

| Contract | Address |
|----------|---------|
| BOOA (ERC-721) | `0x7aecA981734d133d3f695937508C48483BA6b654` |
| BOOAMinter | `0xec96E4C7457B884f4624bA1272470a9bCB1992e8` |
| BOOAStorage | `0x966aB07b061d75b8b30Ae4D06853dDf26d0f4EB0` |
| BOOARenderer | `0xD9Eb24AAe8099E336F7F37164173E81D1bF96aD8` |

### ERC-8004 Identity Registry (16 EVM Chains — CREATE2)

```
Mainnet: 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
Testnet: 0x8004A818BFB912233c491871b3d84c89A494BD9e
```

Chains: Ethereum, Base, Shape, Polygon, Arbitrum, OP Mainnet, Avalanche, BNB Chain, Celo, Gnosis, Scroll, Linea, Mantle, Metis, Abstract, Monad

### Verification Logic

A registration is `verified: true` if either:
1. `nftOrigin.originalOwner == currentNftOwner` — holder registered, optionally transferred 8004 to agent wallet
2. `current8004Owner == currentNftOwner` — both NFT and 8004 in same wallet (e.g., agent wallet)

---

## API Reference

All endpoints are public. No API key required.

```
GET  /api/agent-card?chain={slug}&agentId={id}           # Agent identity + scores
GET  /api/booa-token?network=mainnet&tokenId={id}         # On-chain traits + pixel art
GET  /api/agent-registry/{chainId}/{tokenId}              # Registration status + verification
GET  /api/discover-agents?address={addr}&chain={slug}     # All agents owned by wallet
POST /api/fetch-agent  {"chain":"shape","agentId":42}     # Raw 8004 registration data
GET  /api/gallery?contract={addr}&chain=shape&limit=50    # Browse collection
GET  /api/fetch-nfts?address={addr}&chain=shape           # All NFTs in wallet
GET  /api/stats                                           # Collection statistics
GET  /api/agent-files/{chainId}/{tokenId}                  # ZIP (all files)
GET  /api/agent-files/{chainId}/{tokenId}/identity.md     # IDENTITY.md
GET  /api/agent-files/{chainId}/{tokenId}/soul.md         # SOUL.md
GET  /api/agent-files/{chainId}/{tokenId}/avatar.svg      # On-chain pixel art
GET  /api/agent-files/{chainId}/{tokenId}/agent.json      # Trait data + CAIP ref
GET  /api/agent-files/{chainId}/{tokenId}/erc8004.json    # ERC-8004 registration
```

Full reference: [booa.app/llms.txt](https://booa.app/llms.txt)

---

## Resources

| | |
|---|---|
| **Website** | [booa.app](https://booa.app) |
| **Collection** | [opensea.io/collection/booa](https://opensea.io/collection/booa) |
| **Studio** | [booa.app/studio](https://booa.app/studio) |
| **Bridge** | [booa.app/bridge](https://booa.app/bridge) |
| **8004scan** | [8004scan.io](https://8004scan.io) |
| **GitHub** | [github.com/0xmonas/Khora](https://github.com/0xmonas/Khora) |
| **Blog** | [booa.app/blog](https://booa.app/blog) |
| **API Docs** | [booa.app/llms.txt](https://booa.app/llms.txt) |
| **OWS** | [openwallet.sh](https://openwallet.sh) |

---

*Born on-chain. Owned by you. Ready for anything.*