---
name: Empire Builder
description: Empire Builder AI skill — SmartVault treasuries, leaderboards, boosters, prepare→executeBatch→store distributions, burns, airdrops, Clanker deploys. Self-contained under skill/; follow references/http-api.md and references/workflows.md exactly.
homepage: https://empirebuilder.world
dependencies: [clanker-sdk, viem]
---

# Empire Builder Skill

**Empires** are community treasuries (ERC-4337 SmartVaults on Base `8453` and Arbitrum `42161`) paired with an identity (**Empire ID**). Agents orchestrate HTTP APIs plus wallet-signed txs (`executeBatch` for payouts).

**Base URL:** `https://empirebuilder.world`

**Packages:** `npm install clanker-sdk viem`

---

## How agents should use this skill

Models usually load **`SKILL.md` first** only. Treat this file as **guardrails + routing**. Before writing HTTP bodies, signing flows, or multi-step flows, **open the reference files** listed below—otherwise you will guess missing fields (`signer` vs `signerAddress`, `leaderboardType` values, booster payloads). For **one pipeline story** (especially payouts), follow [`references/workflows.md`](references/workflows.md) step order.

---

## How this skill is structured

Everything agents need lives **inside `skill/`** — no dependency on other folders.

| File | Role |
|------|------|
| **`SKILL.md`** (this file) | Scope, rules, orientation |
| [`references/http-api.md`](references/http-api.md) | Canonical HTTP routes, auth, Empire ID, key JSON shapes |
| [`references/workflows.md`](references/workflows.md) | End-to-end sequences (deploy, distribute, burn, …) |
| [`references/contracts.md`](references/contracts.md) | SmartVault `execute` / `executeBatch`, chains |

---

## Agent constraints (mandatory)

1. **Catalog fidelity.** Only use routes and semantics described in [`references/http-api.md`](references/http-api.md). Do not invent paths or composite undocumented URLs.

2. **Authentication.** Send **`x-api-key`** where [`references/http-api.md`](references/http-api.md) says so. Writes often require EIP-191 **`signature`**, **`message`**, and **`signer`** or **`signerAddress`** — match field names per route.

3. **Treasury payouts.** Integration flow only: **`POST /api/distribute-prepare`** → vault **`owner()`** wallet submits vault **`executeBatch`** txs (**you pay gas**) → **`POST /api/store-distribution`**. Do not substitute random sponsor/UserOp tutorials unless working purely inside the official web app (different pipeline).

4. **`POST /api/distribute-prepare`** signer must equal **`owner()`** on the vault — **not** co-signers / “authorized” SmartVault signers. Those addresses can authorize **UserOperations** in the web app (sponsored **`executeBatch`** via EntryPoint), but they **cannot** use this API path and **cannot** **`execute`** or **`executeBatch`** on the vault with a normal EOA transaction — the contract reverts **`Unauthorized`**. See [`references/contracts.md`](references/contracts.md). On **other** routes, recovered **`signer`** may be checked against **`owner`** / **`co_emperors`** per backend rules — do not assume the same rule as **`distribute-prepare`**.

5. **Empire ID** (often labeled **`tokenAddress`** or **`baseToken`** in JSON/query params): ERC‑20 **`0x…`**, **`fid…`** prefix tokenless empire, or **slug** — **never confused with** SmartVault **`empireAddress`/`treasuryAddress`** unless an endpoint explicitly requires both.

6. **Burns.** Decoded from the burn tx receipt: ERC‑20 **Transfer** to **`0x000…0000`** or **`0x000…dEaD`** for the empire **base** (or attached base if tokenless), then **`POST /api/store-burn`**. If tokens sit **in the SmartVault**, only **`owner()`** can fire a direct vault **`execute`** / **`executeBatch`**; co-signers burn from the treasury in the **website** via sponsored **`executeBatch`** UserOps (Base / Arbitrum). If tokens sit in **any other wallet**, that wallet **`transfer`**s to a burn address — no vault role needed.

---

## At-a-glance: integration surfaces

| Area | Mechanism |
|------|-----------|
| Reads | Mostly open GETs; some routes require API key (see [`references/http-api.md`](references/http-api.md)) |
| Leaderboard payouts | prepare (owner-signed) → `transactions[]` → owner broadcasts `executeBatch` → store-distribution |
| Burns | Eligible **Transfer** in mined tx → store-burn; treasury burns: owner self-paid **`execute`**, or web app UserOp **`executeBatch`** for co-signers |
| Boosters | [`references/http-api.md`](references/http-api.md) — `/api/boosters/...` |
| Token deploy | `get-token-config` → Clanker SDK deploy → `deploy-empire` |

---

## Example prompts

- Walk distribution preparation using leaderboard **`main`** and two ERC‑20s from [`references/workflows.md`](references/workflows.md).
- Build **`curl`** skeletons for `store-distribution` given mined hashes.
- Explain why **`baseToken`** in storage payloads differs from **`empireAddress`**.

---

## Error handling

| HTTP | Meaning |
|------|--------|
| `400` | Bad parameters |
| `401` | API key / signature invalid |
| `403` | Forbidden |
| `404` | Not found |
| `429` | Rate limited |
| `500` | Server error — retry with backoff |

---

## Detail sections — open references next

- **Routes & payloads:** [`references/http-api.md`](references/http-api.md)
- **Step-by-step flows:** [`references/workflows.md`](references/workflows.md)
- **On-chain primitives:** [`references/contracts.md`](references/contracts.md)