---
name: gotchi-finder
description: >
  Fetch Aavegotchi by ID from Base mainnet and display image with full traits.
  Shows on-chain SVG, converts to PNG, and displays complete gotchi stats.
homepage: https://github.com/aavegotchi/gotchi-finder-skill
metadata:
  openclaw:
    requires:
      bins:
        - node
        - npm
      env:
        - BASE_MAINNET_RPC
---

# Gotchi Finder Skill

Find and display any Aavegotchi by ID with complete traits and image.

## Features

- ✅ **Instant ID lookup** - Fetch any gotchi by ID number
- ✅ Fetch any gotchi by ID from Base mainnet
- ✅ Display full traits (BRS, Kinship, Level, XP, Haunt, Name, Owner)
- ✅ Generate PNG images (standard 512x512 or hi-res 1024x1024)
- ✅ Export as SVG (scalable vector graphics)
- ✅ Flexible format options (PNG, hi-res, SVG, or all)
- ✅ Support for all gotchi states (Portal, Gotchi, etc.)
- ✅ Automatic image conversion and delivery

## Usage

### Interactive Workflow (Recommended)

**Step 1: Preview gotchi**
```bash
bash scripts/find-gotchi.sh 9638
```

**Presentation order:**
1. 🖼️ Gotchi image (PNG preview 512x512) - **shown first**
2. 📊 Complete trait information - **shown below image**
3. 📥 Download options menu - **at the end**

**Step 2: User chooses format**
User can then request specific format(s):
```bash
# Hi-res PNG
bash scripts/find-gotchi.sh 9638 --format hires

# SVG vector
bash scripts/find-gotchi.sh 9638 --format svg

# All formats
bash scripts/find-gotchi.sh 9638 --format all
```

### Format Options

- `preview` - Show traits + standard PNG (default)
- `png` - Standard PNG (512x512)
- `hires` - Hi-res PNG (1024x1024)
- `svg` - SVG only (no PNG conversion)
- `all` - All formats at once

### Examples

**Preview first (conversational flow):**
```bash
# Show gotchi info + preview image
bash scripts/find-gotchi.sh 9638

# Then user picks format
bash scripts/find-gotchi.sh 9638 --format hires
```

**Direct download (skip preview):**
```bash
# Get hi-res immediately
bash scripts/find-gotchi.sh 9638 --format hires

# Get all formats at once
bash scripts/find-gotchi.sh 9638 --format all
```

**Output Files:**
- `gotchi-{ID}.json` - Complete metadata (always)
- `gotchi-{ID}.svg` - Vector image (always)
- `gotchi-{ID}.png` - Standard PNG (preview/png/all)
- `gotchi-{ID}-hires.png` - Hi-res PNG (hires/all)

## Display Format

### Live Gotchis (Status 3)

**Single message with image + caption:**

Image: Gotchi PNG (512×512)

Caption:
```
👻 Gotchi #{ID} "{Name}"

📊 Stats:
⭐ BRS: {brs} (Modified: {modifiedBrs})
💜 Kinship: {kinship}
🎯 Level: {level}
✨ XP: {xp}
🏰 Haunt: {haunt}
🔒 Locked: {Yes/No}

🎭 Traits:
• Energy: {value}
• Aggression: {value}
• Spookiness: {value}
• Brain Size: {value}
• Eye Shape: {value}
• Eye Color: {value}

📥 Download options:
• Standard PNG (512×512)
• Hi-res PNG (1024×1024)
• SVG (vector)
• All formats
```

### Portals (Status 0-1)
**Single message:** Portal image with status info as caption

## Technical Details

**Blockchain:**
- Chain: Base mainnet (8453)
- RPC: https://mainnet.base.org
- Diamond: 0xA99c4B08201F2913Db8D28e71d020c4298F29dBF

**Dependencies:**
- Node.js with ethers v6
- Sharp library for image conversion

**Status Codes:**
- 0: Unopened Portal
- 1: Opened Portal
- 2: Gotchi (rare on Base)
- 3: Gotchi (standard on Base)

## Files

- `scripts/find-gotchi.sh` - Main entry point
- `scripts/fetch-gotchi.js` - Fetch from blockchain
- `scripts/svg-to-png.js` - Convert SVG to PNG
- `package.json` - Node dependencies

## Installation

```bash
cd /home/ubuntu/.openclaw/workspace/skills/gotchi-finder
npm install
```

## Examples

**Find your gotchi:**
```bash
bash scripts/find-gotchi.sh 9638
```

**Find any gotchi:**
```bash
bash scripts/find-gotchi.sh 5000
```

**Find multiple gotchis:**
```bash
for id in 9638 21785 10052; do
  bash scripts/find-gotchi.sh $id
done
```

---

Built with 💜 by AAI