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 — mainnet only. There is no testnet or sandbox API documented here.

Packages (pinned): npm install clanker-sdk@4.2.16 viem@2.48.0 — versions match the YAML frontmatter; use a lockfile in automation; avoid @latest for reproducibility.

Skill copies: If you sync from homepage, diff against a trusted checkout before relying on it in scripts.

Intentional product behavior (not documentation bugs)#

The integration surface is meant to hit production chains with vault owner() authority. “Hardening” belongs in product code, infra, and operator tooling—this skill only describes the API/contract shape.

• All writes are live on Base 8453 / Arbitrum 42161 unless you stick to reads.
• distribute-prepare + owner-broadcast executeBatch is the designed API path; SmartVault owner() is required on-chain (see references/contracts.md).
• POST /api/store-distribution persists from mined transactionHashes (receipt-backed): recorded payouts follow on-chain execution, not prepare JSON alone. You still must pass correct empireAddress, baseToken (Empire ID), and leaderboard fields so rows attach to the right empire ( http-api.md).
• Registry/scanner warnings about “agent + wallet + mainnet” reflect that intentional design, not missing caveats in this file.

---

How agents should use this skill#

Models usually load SKILL.md first only. Treat this file as routing + constraints. 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 step order.

---

When NOT to use this skill#

Stop and pick a different approach if any of these apply:

• End-user wallet UX inside the Empire web app. The website signs sponsored ERC‑4337 UserOperations (paymaster-funded executeBatch via EntryPoint) for co-signers — not the prepare → owner-broadcast → store path this skill describes. Use the in-app flow (or its dedicated front-end client code), not these HTTP routes.
• Co-signer / "authorized signer" automation. Co-signers cannot call vault execute/ executeBatch directly (reverts Unauthorized) and cannot drive POST /api/distribute-prepare — that route requires owner(). If you are a co-signer, either (a) trigger a UserOp through the web app, or (b) escalate to the vault owner.
• Generic ERC-4337 / paymaster / bundler tutorials. This skill does not teach you to build a sponsor, bundler, or EntryPoint integration. Don't graft /alchemy-sponsor-userop-style helpers or legacy distribute-v3 endpoints onto these flows.
• Non-Empire token deploys. Plain Clanker SDK deploys without an Empire are out of scope — use the Clanker docs directly. This skill only covers Clanker → deploy-empire wiring.
• Testnets / local dev. No sandbox endpoint exists. If you need a dry-run, read-only GETs are safe; do not invent /sepolia/..., chainId: 84532, or staging hosts.
• Mass user-to-user transfers from random EOAs. Use a normal ERC-20 transfer from the holding wallet — vault roles, prepare/store, and distribution routes don't apply.

---

Empire ID vs SmartVault address (read this first)#

Three input shapes resolve to one Empire, but they are not the SmartVault address:

ShapeLooks likeWhere it appearsToken empire0x + 40 hex (the ERC‑20 base token)most tokenAddress / baseToken paramsFarcaster tokenlessfid + digits (e.g. fid12345)tokenless empires anchored to a Farcaster fidCustom tokenless slugalphanumeric slugtokenless empires with a custom identity

• Empire ID is identity. Often spelled tokenAddress, baseToken, empire_id, or sits in the path segment /api/empires/[empire_id].
• SmartVault address is the on-chain treasury contract. Spelled empire_address / empireAddress / treasuryAddress. Resolve it from GET /api/empires/[empire_id].
• They are never interchangeable unless an endpoint explicitly takes both. Do not pass an fid… Empire ID where a contract address is required, and do not pass the SmartVault address where Empire ID is required (e.g. store-distribution wants both, with distinct field names).

See references/http-api.md → Empire ID for the full type table.

---

How this skill is structured#

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

FileRole**SKILL.md** (this file)Scope, rules, orientationreferences/http-api.mdCanonical HTTP routes, auth, Empire ID, key JSON shapesreferences/workflows.mdEnd-to-end sequences (deploy, distribute, burn, …)references/contracts.mdSmartVault execute / executeBatch, chains

---

Agent constraints (mandatory)#

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

2. Authentication. Send x-api-key where 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. 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 vs SmartVault address. Per the dedicated section above, tokenAddress / baseToken / empire_id is identity (ERC‑20, fid…, or slug); empireAddress / treasuryAddress is the on-chain vault. Confusing them is the most common skill-failure mode — re-check field names against references/http-api.md before sending any write.

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#

AreaMechanismReadsMostly open GETs; some routes require API key (see references/http-api.md)Leaderboard payoutsprepare (owner-signed) → transactions[] → owner broadcasts executeBatch → store-distributionBurnsEligible Transfer in mined tx → store-burn; treasury burns: owner self-paid execute, or web app UserOp executeBatch for co-signersBoostersreferences/http-api.md — /api/boosters/...Token deployget-token-config → Clanker SDK deploy → deploy-empire

---

Example prompts#

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

---

Error handling#

HTTPMeaning400Bad parameters401API key / signature invalid403Forbidden404Not found429Rate limited500Server error — retry with backoff

---

Detail sections — open references next#

• Routes & payloads: references/http-api.md
• Step-by-step flows: references/workflows.md
• On-chain primitives: references/contracts.md