@chaindaddy/mcp 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaindaddy/mcp",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "MCP server for Chain Daddy: search tickers, launch or import a token, and run its creator store",
   "mcpName": "io.chaindaddy/mcp",
   "homepage": "https://docs.chaindaddy.io/developer/store-and-rewards#tools-for-agents",
@@ -56,6 +56,7 @@
   },
   "files": [
     "build",
+    "skills/*/SKILL.md",
     "README.md"
   ]
 }

package/skills/add-crypto-to-your-game/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: add-crypto-to-your-game
+description: The end-to-end path for putting a game, app or site on crypto with Chain Daddy - pick or launch a token, sell items for it, sign players in with their wallet, verify purchases on your server, and run it all on a no-money test store first. Use when someone wants to add a token, sell in-game items for crypto, give holders perks, or "add crypto" to a game, app or dApp.
+license: MIT
+---
+
+# Add crypto to your game or app
+
+Chain Daddy gives a token a verified page and a **store**: items you sell for that token, a record of what
+each wallet owns, and a signed receipt for every purchase. Your game reads what a player owns; it never
+moves money.
+
+## How it fits together
+
+```
+your token ── its page on chaindaddy.io ── its store (items, what each wallet owns, receipts)
+                                               │
+          your game client ── asks to buy ─────┤  the buyer's wallet pays your payout wallet on chain
+                                               │
+          your server ── store key ────────────┘  creates orders, verifies receipts, spends items
+```
+
+1. **Money never passes through your code.** The buyer's wallet pays the token's payout wallet directly,
+   in one on-chain transaction. Chain Daddy then grants the item and signs a receipt.
+2. **The client asks, the server decides.** Anything with value (spending credits, a ranked result, a
+   prize) is decided on your server, with a store key only the server holds.
+3. **Test first.** A test store runs the whole loop with no wallet, no chain and no money.
+
+## What the human needs first
+
+Check these before writing code, and stop with a clear next step if one is missing:
+
+| Need | How to check | If missing |
+|---|---|---|
+| A token page they own or manage, and its **chain key** (`base`) and **crown id** (the registration id) | `find-and-check-a-token` skill | Import a token they made elsewhere, or `launch-a-token` |
+| A plan that can open a store: Developer, Partner or Enterprise, or Developer Beta Program membership | `GET https://api.chaindaddy.io/api/v2/iap/eligibility` (signed in) | Any paid plan, then sign the agreement at https://chaindaddy.io/_developer |
+| Signed in on this computer | `chaindaddy whoami` | They run `chaindaddy login` and approve in the browser (any wallet or email/social sign-in); the CLI and the local MCP server both use it. A server or CI job gets a `cd_live_…` key instead (`chaindaddy keys create`) |
+
+Never ask the human to paste a key into the chat. Ask them to set it as an environment variable.
+
+## The path
+
+### 1. Pick the token
+
+- **Their own token, made elsewhere:** they import it on chaindaddy.io (one fee, or free for established
+  tokens). A store can only sell for a token whose page the wallet owns or manages.
+- **A new token:** see `launch-a-token`. A token launched in a Chain Daddy launchpad pool pays **0%** on
+  store sales; any other token pays **2.5%**, taken out of the price at checkout.
+
+### 2. Decide where the game runs
+
+| The game runs… | How it sells | Skill |
+|---|---|---|
+| On the token page, as a Crown App | Sends the `iap-purchase` action; the page shows its own purchase sheet and handles the wallet. No server or payment code needed | `build-a-crown-app` |
+| In your own site, app or client | Your server creates an order; your client pays with the order's `payment` block | `sell-items-in-your-app` |
+| Anywhere, with no code | A payment link: `https://chaindaddy.io/<symbol>/<chain>?buy=<sku>` | `sell-items-in-your-app` |
+
+### 3. Design the catalog
+
+| Type | Use it for |
+|---|---|
+| `non_consumable` | Owned for good, one per wallet: a skin, a badge, a level pack |
+| `consumable` | Used up: credits, boosts. A bundle `grants` other items |
+| `timed` | Access for a while: a season pass, a rental |
+| `unlock` | Never sold. Held while a rule holds, e.g. "holds at least 1,000 tokens" |
+
+Put what the game needs to apply an item in its `metadata`: that JSON is the contract between the store and
+the game. Price in dollars (`priceUsdMicros`, with `minPrice` / `maxPrice` bounds) and take payment in the
+token, so prices don't swing with the market.
+
+### 4. Build against the test store
+
+Open the test store beside the live one (`iap_open_test_store` / `chaindaddy iap store test <storeId>`), make
+a `cd_iap_test_…` key on it, then run the whole loop: create an order, pay it with `iap_test_pay`, verify the
+receipt (`livemode: false`), read and spend the items, and receive the webhook. Details in
+`sell-items-in-your-app`.
+
+### 5. Know who the player is
+
+- In a Crown App: the `session-token` action gives a short-lived token your server verifies.
+- On your own site or app: Sign in with Chain Daddy (standard OpenID Connect) - see `sign-in-with-chain-daddy`.
+
+Both identify the player by wallet (`sub`). Key accounts by that wallet.
+
+### 6. Verify on your server
+
+Verify every receipt and session token on the server before acting on it - see `verify-receipts-and-sessions`.
+Deliver on `confirmed`, credit each `orderId` once, and treat the store's item ledger
+(`GET …/entitlements?wallet=`) as the source of truth.
+
+### 7. Go live
+
+Switch the server to the live store's key. Read the store id from the key (`GET /api/v2/iap/stores` with a
+store key returns its own store) so nothing else changes. In production, check `storeId` is the live store and
+`livemode` is `true`.
+
+To pay out real tokens as prizes, see https://docs.chaindaddy.io/developer/token-prizes (live stores only).
+
+## Mistakes to avoid
+
+- Granting an item on `paid`. `paid` means the payment is on chain but still confirming. Deliver on `confirmed`.
+- Trusting a receipt or session token because the client sent it. Verify it on the server, every time.
+- Shipping a store key, account key or webhook secret in client code, a repo or a log.
+- A new random idempotency key on each retry. Build it from something stable (`user-42-milestone-10`).
+- Items with a random outcome (loot boxes, mystery boxes): not allowed.
+- Describing items as money. They can't be transferred between wallets or exchanged for tokens or cash.
+- Asking for a private key or seed phrase, or sending a transaction for the human. They sign in their own wallet.
+
+## Docs
+
+- Store and rewards: https://docs.chaindaddy.io/developer/store-and-rewards
+- Test your integration: https://docs.chaindaddy.io/developer/test-your-integration
+- Build a game: https://docs.chaindaddy.io/developer/build-a-game
+- Everything, for an agent: https://docs.chaindaddy.io/llms.txt (raw pages at `/md/<path>.md`)

package/skills/build-a-crown-app/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: build-a-crown-app
+description: Build, test and publish a Crown App - an app any Chain Daddy token page can install - as a sandboxed React widget, a headless runner that receives signed events, or both. Covers the CLI path, capp.json manifest and permissions, the sandbox rules, actions like iap-purchase and session-token, local testing, review, and what paid apps can and can't do today. Use when someone wants to put a game, storefront, gallery or tool on a token page.
+license: MIT
+---
+
+# Build a Crown App
+
+A Crown App runs on token pages. The token's owner adds it from the page's **Apps** tab; every app is free to
+install on every plan.
+
+| Type | What it is | Scaffold |
+|---|---|---|
+| `widget` | A React component, sandboxed in a frame on the page | `chaindaddy app init widget my-app` |
+| `headless` | A runner: your HTTPS endpoint that receives the page's signed events | `chaindaddy app init headless my-runner` |
+| `full` | A widget and a runner | `chaindaddy app init full my-app` |
+
+Starters with working code: `game` (three.js arcade game with a shop), `interactive` (canvas piece),
+`community` (poll, links, holder count): `chaindaddy app init game my-game`.
+
+## Who can publish
+
+- **Testing locally needs no account.** Start there.
+- **Publishing** needs any active paid plan (not a trial) and the Developer Beta Program Agreement, signed at
+  https://chaindaddy.io/_developer with the wallet that holds the plan. Check with `chaindaddy app whoami`.
+- Every build is a signed `.capp` package, checked automatically, then reviewed by a person.
+
+## The path
+
+```bash
+npm install -g @chaindaddy/cli@beta           # Node 20+
+chaindaddy app init widget my-app && cd my-app && npm install
+npm run dev                                   # or chaindaddy app dev: a token page on 127.0.0.1:5180
+# when it works:
+chaindaddy login                              # the human approves in their browser; no key to paste
+npm run validate && npm run build && npm run scan
+npm run pack && npm run sign && npm run submit
+chaindaddy app submit --request-review        # or press Submit for review on the build in the portal
+```
+
+Add `--json --non-interactive` to CLI calls you run as an agent. Exit codes: `0` ok, `1` user error, `2`
+system, `3` validation failed, `4` auth, `5` server.
+
+`app dev` runs the widget in the real sandbox at real slot sizes, answers every host action from sample data
+(a store, purchases, sign-in, signatures), refuses what a real page refuses, and prints every violation. Fix
+those before submitting.
+
+## The widget
+
+- One named export (a plain function component, the name in `entryComponent`), one ESM file, at most
+  2,000,000 bytes, with `react`, `react-dom` and `react/jsx-runtime` left external. `chaindaddy app build`
+  enforces this.
+- Props: `appData` (the token's data), `settings` (the owner's settings, from your `configSchema`), `theme`
+  (use its colors), `connectedAddress`, `signedIn`, `isOwner`, `breakpoint`, `onAction`, and
+  `subscribeStore` (with `iap:purchase`).
+- Everything sensitive goes through `onAction({ type, … })`, which resolves `{ ok, data }` or `{ ok: false, error }`.
+
+## Permissions (`capp.json` → `permissions`)
+
+Declare only what you use; the owner sees each one before installing and the scan checks the bundle matches.
+
+| Permission | Lets the app |
+|---|---|
+| `iap:purchase` | Sell from this token's store: `onAction({ type: 'iap-purchase', sku, quantity })`. The page shows its own sheet and the viewer's wallet pays; your app never sees a wallet or names an amount |
+| `net:connect` | Reach your own servers listed in `network.origins` (exact `https://` / `wss://` hosts), and ask for a `session-token` |
+| `fetch:self-api` | Call the platform API (`/api/...`) with no cookies |
+| `storage:local` | Keep `localStorage` between visits (512K characters) |
+| `notify:user` | Send the signed-in user a notification (5 a day per user) |
+| `wallet:trade` | Open the token's Buy sheet |
+| `wallet:transaction`, `wallet:sign` | Propose a transaction or an EIP-712 signature, limited to your token and contracts declared in `wallet`; the viewer sees it decoded and confirms |
+| `clipboard:write`, `navigate:internal`, `ui:fullscreen` | Clipboard, move to another page, fullscreen - each on a tap |
+
+Data scopes go in `requiredData` (`profile:basic`, `market:price`, `market:holders`, …).
+
+## Selling inside the app
+
+```ts
+const res = await onAction({ type: 'iap-purchase', sku: 'credits.100', quantity: 1, appAccountToken: user.id });
+// res.data.status: 'confirmed' | 'paid' | 'cancelled' | 'failed'; 'paid' settles later
+props.subscribeStore?.((e) => {
+  if (e.type === 'store:order' && e.status === 'confirmed') unlock(e.sku, e.receipt);
+  if (e.type === 'store:entitlements') refreshInventory();
+});
+```
+
+Read the catalog and the viewer's items with `api-call` (`/api/v2/iap/public/…`, `/api/v2/iap/me/…`). An app
+sells from the store of the token page it is on. The store itself: `sell-items-in-your-app`.
+
+## Your own server
+
+Declare `net:connect` with your origins. Get `onAction({ type: 'session-token' })` → `{ token, expiresAt }`, send
+it to your server, and verify it there (`verify-receipts-and-sessions`). To sign a visitor in, send
+`onAction({ type: 'sign-in' })` from a button they tap - don't ask their wallet to sign a login of your own.
+
+## Runners
+
+A runner receives signed events (`runner.events` in the manifest) at `runner.endpointUrl`. Verify
+`X-App-Signature` (hex HMAC-SHA256 of the raw body, secret hex-decoded) before processing, dedupe by
+`eventId`, and answer quickly. Per-token data goes through the Action API (`apps:storage:write`).
+
+## Paid apps
+
+Every app is free to install. Charging for an app itself, with a revenue share for its developer, is in
+development and not live: the beta agreement includes no payment to developers. What works today is selling
+items for the token from inside the app (above), at 2.5% or 0% on a Chain Daddy launchpad token. Check
+https://docs.chaindaddy.io/developer/paid-apps for the current state before promising anything.
+
+## Mistakes to avoid
+
+- `eval`, `new Function` or `document.cookie`: the frame refuses them and the scan fails the build.
+- Fetching anything not declared: images and calls to other hosts are blocked and reported as violations;
+  enough reports disable the app on every page.
+- Setting `location` or following a link in the frame: it takes your app off the page. Use `navigate`.
+- Keying signed-in state on `connectedAddress`; use the `signedIn` prop.
+- Putting a store key, API key or secret in the bundle. The bundle is public.
+- Declaring permissions you don't use: review refuses them, and owners see them.
+- An app name another developer uses: names are unique.
+
+## Docs
+
+https://docs.chaindaddy.io/developer/quickstart · widgets · manifest · actions · security · runners ·
+submission · build-a-game · engine-apps (Godot and Unity web exports) - all under
+https://docs.chaindaddy.io/developer/

package/skills/check-token-health/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: check-token-health
+description: Read the health of the tokens a wallet has registered on Chain Daddy - the 0-100 score, which registrations are at risk or counting down to expiry, why, and what the owner can do. Read-only. Use when someone asks how their tokens are doing, whether they could lose a ticker, or what their health score means.
+license: MIT
+---
+
+# Check token health
+
+Every registered token has a health score from 0 to 100, updated daily. If it stays **below 60 for 30 days
+in a row**, the registration expires and anyone who can prove ownership of the token can register the ticker,
+first come, first served. Read-only: this skill changes nothing.
+
+## Tools
+
+| Need | MCP | CLI | HTTP |
+|---|---|---|---|
+| Every registration a wallet owns | `list_crowns` (`owner`) | `chaindaddy status --wallet <addr> --json` | - |
+| One token's score | `check_heartbeat` | `chaindaddy status --symbol S --chain base` | `GET /api/v2/heartbeat/{symbol}/{chain}` (EVM) |
+| Score history | - | - | `GET /api/v2/heartbeat/{symbol}/{chain}/history` |
+| Holder spread | `get_holders` | - | `GET /api/v2/registration/{id}/holders` |
+
+HTTP calls from your own code need `X-API-Key: cd_live_…`. The remote MCP server's read tools need no key.
+
+## Steps
+
+1. List the wallet's registrations. Ask for the wallet address; never for a key or a signature.
+2. Read each one's score and classify it:
+
+   | Score | Status | Meaning |
+   |---|---|---|
+   | 80-100 | Healthy | In good standing |
+   | 65-79 | Moderate | In good standing, worth a look |
+   | 60-64 | At risk | The owner gets a "Token at risk" alert |
+   | below 60 | Inactive | The 30-day countdown is running |
+   | below 60 for 30 days | Expired | The ticker is open to register again |
+
+   A registration in its first 30 days is in its **grace period**: tracked, but it can't be reclaimed
+   whatever the score. Releasing and registering again doesn't reset it.
+3. Show a short table, worst first: symbol, chain, score, status, and days left where a countdown runs.
+4. For each token at risk, explain the score's parts:
+   - **Age, 50%:** full marks for 30 days, then steps down over two years (90, 80, 70, 60, then 50). An older
+     token needs real trading and holders to stay above 60.
+   - **Trading volume, 30%:** smoothed (last 24 h 70%, 7-day average 30%) and capped at 100x the pool's
+     liquidity, so wash trading doesn't help.
+   - **Holder spread, 20%:** concentration in the top 10 and top 50 wallets, flagged wallets (snipers,
+     bundlers, insiders, sandwich traders), how many wallets hold half the supply, and the raw count.
+     Splitting a balance across new wallets lowers it.
+5. Say what helps: real trading, supply spread across real holders, health alerts on, and registering from a
+   multisig so a teammate can act. Point to the token manager's **Health** tab.
+
+## If it expired
+
+Search shows it as **Inactive**. The original owner has no special claim: whoever registers first, at the
+normal price, keeps it, and the page's details and manager roles are cleared. Tell the owner plainly and
+point them to https://docs.chaindaddy.io/getting-started/import-an-existing-token. Don't register it for them.
+
+## Mistakes to avoid
+
+- Suggesting trades with yourself, splitting wallets or other ways to game the score. They are filtered out
+  or lower it.
+- Promising support can recover an expired ticker someone else registered. It can't.
+- Reading the score as a rating of the token's quality or safety. It measures activity.
+
+## Docs
+
+- https://docs.chaindaddy.io/platform/heartbeat
+- https://docs.chaindaddy.io/alerts/

package/skills/export-a-listing/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: export-a-listing
+description: Prepare a registered token's details for listing and screener sites (CoinGecko, CoinMarketCap, DEX Screener, DEXTools, Birdeye) from its Chain Daddy page, check what is missing first, and explain the public Token List. Read-only; the human submits each form. Use when someone wants their token listed, or asks what a listing site needs.
+license: MIT
+---
+
+# Export a listing
+
+A token page already holds what listing sites ask for: name, ticker, description, logo, socials, contract.
+This skill gathers it, flags gaps, and hands the human ready-to-paste fields. Each site decides for itself
+whether to list a token; nothing here guarantees a listing.
+
+## Tools
+
+| Need | MCP | HTTP |
+|---|---|---|
+| The page's data | `get_crown` | `GET /api/v2/registration/{id}` |
+| Fields for one site | `generate_listing` (`format`: `coingecko`, `coinmarketcap`, `dexscreener`, `tokenlist`) | - |
+| Every format at once | `export_listing` | - |
+| The public Token List | - | `GET /api/v2/tokenlist?chainId=8453` (no key) |
+
+In the browser: the token manager → chain switcher → gear → **Listing Export**, with a guided wizard for
+each site.
+
+## Steps
+
+1. Find the token's crown id (`find-and-check-a-token`) and read its page data.
+2. Check completeness before generating. Most sites want: name, ticker, contract address, description,
+   website, logo (512 px or larger for screener upgrades), and socials. If something is missing, the owner
+   adds it in the token manager first; a missing field means an incomplete submission.
+3. Generate the fields for the site the human picked, and show them ready to copy, with the site's own
+   form link.
+4. Say what each site charges, from the docs page (screener upgrades are paid to those sites; CoinGecko and
+   CoinMarketCap are free to apply). Chain Daddy takes nothing.
+
+## The Token List
+
+Chain Daddy publishes every active, verified EVM registration in the standard Token List format that
+wallets and exchanges read: `GET https://api.chaindaddy.io/api/v2/tokenlist`. A token is in it when its
+registration is active, its contract is set and its decimals are known. Each entry carries
+`extensions.tokenId` (the crown id) and `extensions.verified`. Solana tokens are not in it.
+
+## Mistakes to avoid
+
+- Submitting a form for the human or paying a listing fee. They submit and pay.
+- Promising a listing or a timeline. Each site has its own minimums for volume, holders and liquidity.
+- Generating with gaps instead of flagging them first.
+
+## Docs
+
+https://docs.chaindaddy.io/creator-tools/listing-export

package/skills/find-and-check-a-token/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: find-and-check-a-token
+description: Read-only lookups on Chain Daddy - find a token by ticker, name or contract address on every supported chain, tell the verified token from copycats, read who registered it and how they proved ownership, and check its health and holder spread. Use when someone asks "is this the real token", "who owns this ticker", "is this ticker free", "find the token for my game", or needs a token's chain key and crown id. Never buys, sells or signs anything.
+license: MIT
+---
+
+# Find and check a token
+
+Everything here is read-only. Nothing in this skill moves money, signs or changes anything.
+
+## Tools
+
+| Need | MCP | HTTP (`https://api.chaindaddy.io`) | CLI |
+|---|---|---|---|
+| Search | `search_symbols` (filters), `search_symbol` | `GET /api/v2/search?q=…` | - |
+| One token on one chain | `get_token` | `GET /api/v2/token/{symbol}/{chain}` | `chaindaddy status --symbol S --chain base` |
+| A registration (token page) | `get_crown`, `list_crowns` | `GET /api/v2/registration/{id}` | `chaindaddy status --crown <id>` |
+| Health | `check_heartbeat` | `GET /api/v2/heartbeat/{symbol}/{chain}` (EVM) | `chaindaddy status --wallet <addr>` |
+| Holder spread | `get_holders` | `GET /api/v2/registration/{id}/holders` | - |
+| Verified token list (EVM) | - | `GET /api/v2/tokenlist?chainId=8453` (no key) | - |
+
+The remote server at `https://api.chaindaddy.io/mcp` needs no key for its read-only tools. Calls from your own
+code need an API key as `X-API-Key: cd_live_…` (from https://chaindaddy.io/_api); without one the API answers
+`401 api_key_required`.
+
+## Search
+
+`GET /api/v2/search?q=PEPE` searches symbols, names, or a contract address across every chain. Useful
+parameters: `chain` (`eth`, `base`, `arbitrum`, `polygon`, `bnb`, `avax`, `robinhood`, `solana`, …),
+`exact=true`, `crownsOnly=true`, `sort` (`relevance`, `market_cap`, `volume`, `liquidity`, `holders`, `age`, …),
+`pageSize` (max 100), and `refresh=true` right after a launch or import.
+
+Each result has `type`: `crown` (registered), `token` (exists, not registered) or `available` (no token with
+that symbol on that chain), plus `token` (address, market data, holders) and `crown` (status, `tokenId` = the
+crown id, `owner`, `verificationMethod`).
+
+| Status | Meaning |
+|---|---|
+| `available` | No token with this symbol on this chain |
+| `unclaimed` | A token exists; nobody has registered it |
+| `grace_period` | Registered in the last 30 days |
+| `claimed` | Registered: this is the verified token for this ticker on this chain |
+| `inactive` | The registration lapsed; the ticker is open to import again |
+
+## Is this the real token?
+
+1. Search the ticker. Many tokens share a symbol, on one chain and across chains.
+2. The verified one on a chain is the result with a registration (`hasCrown: true`, status `claimed` or
+   `grace_period`). Read `crown.verificationMethod` - how the owner proved control of the contract: its
+   owner or admin, its deployer, its mint or update authority (Solana), a launchpad's creator record, an
+   ENS record, or holding more than half the supply.
+3. **Compare the contract address**, never the name or logo. A copycat is a token using the same ticker or
+   one a letter or two off; it has its own address. Hand the human the verified address and the page link
+   (`shareUrl`, or `https://chaindaddy.io/<symbol>`).
+4. A registration says who proved control of the contract. It is not an audit, an endorsement or a safety
+   rating. Say so.
+
+## Health and holders
+
+- Health is 0-100, updated daily: age 50%, trading volume 30% (wash trading filtered), holder spread 20%.
+  Below 60 for 30 days in a row, the registration expires and the ticker opens to anyone who can prove
+  ownership, first come, first served.
+- `get_holders` reports concentration (top 10/50/100/200 share), how many wallets hold half the supply, and
+  counts of wallets flagged as snipers, bundlers, insiders or sandwich traders. Data refreshes daily.
+- Report these as facts with their date. Don't turn them into advice to buy or sell.
+
+## For developers
+
+To build on a token you need its **chain key** (e.g. `base`) and **crown id** (`crown.tokenId`). Both come from
+the search result. Opening a store or building a Crown App for it needs the owner's or a manager's wallet.
+
+## Mistakes to avoid
+
+- Treating the symbol as unique, or trusting a name or logo. Only the contract address identifies a token.
+- Calling an unregistered or copycat token "fake" or "a scam". Say what the data shows: it is not the
+  registered token for that ticker.
+- Reading a cached result right after a launch; pass `refresh=true`.
+- Price predictions, buy or sell advice, or "safe" ratings. Report the numbers.
+- Placing a trade. This skill reads only.
+
+## Docs
+
+- https://docs.chaindaddy.io/api-reference/endpoints/search
+- https://docs.chaindaddy.io/token/verification-methods
+- https://docs.chaindaddy.io/platform/heartbeat
+- https://docs.chaindaddy.io/alerts/ (copycat alerts for owners)

package/skills/launch-a-token/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: launch-a-token
+description: Help a human launch a new token with Chain Daddy, or bring one they already made - check the ticker, compare a launchpad pool against a one-time-fee token, explain fees and what is permanent, and prepare the launch. The agent never holds keys and never sends the launch - it prepares, the human signs on chaindaddy.io or runs the final CLI command. Use when someone wants to launch, create, mint or deploy a token, or pick where to launch.
+license: MIT
+---
+
+# Launch a token
+
+**The rule: you prepare, the human launches.** A launch is irreversible and costs real money or gas. Never
+ask for a private key or seed phrase, never send a launch, buy or payment with the human's key or session,
+and never call a broadcast endpoint for them. Check, compare, write the config, dry-run it, then hand over
+one clear step for the human to take.
+
+## 1. Check the ticker
+
+- MCP: `search_symbols` (or `search_symbol`); HTTP: `GET /api/v2/search?q=<SYMBOL>&exact=true` (send
+  `X-API-Key`); CLI: `chaindaddy status --symbol <S> --chain <chain>`.
+- Per chain, the status is `available` (no token), `unclaimed` (a token exists, unregistered), `claimed` /
+  `grace_period` (registered to someone), or `inactive` (lapsed). A name taken on one chain can be open on another.
+- Symbol: 1-16 characters; Solana caps at 10.
+- If the human already made the token elsewhere, they **import** it instead: they prove ownership on
+  chaindaddy.io (deployer, owner, mint or update authority, launchpad creator, or majority holder) and pay one
+  fee, free for established tokens. Guide: https://docs.chaindaddy.io/getting-started/import-an-existing-token
+
+## 2. Pick what creates the token
+
+| | Launchpad pool | One-time fee |
+|---|---|---|
+| What it creates | The token and its trading pool, liquidity locked | A plain ERC-20 (SPL on Solana), no pool |
+| Up front | Nothing (network fee aside) | A flat fee per chain, token page included (10% off on two or more chains) |
+| Chain Daddy's share | Part of the pool's trading fee, set by the creator's plan **at launch** and fixed for that token | None |
+| Store fee on items later | 0% | 2.5% |
+| Where | https://chaindaddy.io/_launch | chaindaddy.io → **Launch New Token** → **Add to Cart** |
+
+Show prices from the live source, not from memory: `get_pricing` / `chaindaddy estimate --symbol S --chains
+base,arbitrum` for the one-time fee; `GET /api/v2/factory/evm/launchpad/capabilities?chainId=<id>` for what a
+launchpad chain can run (read it each time; values change).
+
+The launch form can also launch on launchpads Chain Daddy doesn't run, and the token page is still free:
+`list_launch_venues` / `GET /api/v2/launch/venues`. For each venue show **both** numbers per $100 traded -
+what traders pay (`traderFeeBps`) and what reaches the creator (`creatorBps`) - in the order returned. Don't
+call any venue best: a venue can pay the creator more by charging traders more.
+
+## 3. Say what is permanent
+
+- Symbol, total supply and decimals can never change. Token settings can be switched off later, never on.
+  Renouncing ownership can't be undone.
+- On a launchpad pool, the fee split is fixed when the pool is created. A plan bought later applies to the
+  next launch.
+- None of a launchpad token's supply goes to the creator unless they keep a vested team allocation or buy
+  at launch.
+
+Get an explicit yes from the human on each before they launch.
+
+## 4. Prepare, then hand over
+
+**Easiest, any human:** send them to https://chaindaddy.io/_launch (pool) or the **Launch New Token** flow
+(one-time fee) with the choices written out. They sign in, review and confirm in their own wallet.
+
+**From the terminal** (`npm i -g @chaindaddy/cli@beta`):
+- Pool: write the request JSON (fields in https://docs.chaindaddy.io/api-reference/endpoints/launchpad-api),
+  then `chaindaddy launchpad launch --config launch.json --dry-run --rpc <url>` to build and simulate only.
+  The human approves in their own wallet: `chaindaddy launchpad login start --address <wallet> --signer <s>`,
+  where `<s>` is `walletconnect` (a QR code for any phone or desktop wallet), `browser` (a chaindaddy.io page,
+  the only option for email/Google/Apple/X sign-in wallets), `ledger`, `trezor`, `keystore`, or `external`
+  (prints what to sign; finish with `--sig`). Then they run the same command **without** `--dry-run`. A Safe:
+  `--safe <addr> --rpc <url>` writes an approveHash plan the owners sign.
+  Run non-interactively, a command waiting on a signature prints one JSON line, `{"sign_request": {...}}`, with
+  a URL or WalletConnect URI and a match code. Show it to the human and wait; never try to sign it yourself.
+- One-time fee: `chaindaddy create --symbol S --name "N" --chains base --supply 1000000000 --dry-run`; the
+  human runs it without `--dry-run`. It asks for their wallet and confirms the fee.
+- Another launchpad: `build_venue_launch` returns an **unsigned** transaction. The human's own wallet signs
+  and sends `transactions[0]`; then `submit_venue_launch` with the hash, and poll `get_venue_launch` until
+  `confirmed` (token page free) or `failed` (`failureReason`).
+
+Rehearse on testnet first when the human wants to: Base Sepolia (`chainId` 84532) against
+`https://staging-api.chaindaddy.io`.
+
+## 5. After the launch
+
+- The token page: a launchpad launch registers it for free (the server may do it; check
+  `GET /api/v2/factory/evm/launchpad/registration?chainId=&token=`). A one-time-fee token is registered with
+  the order. Then set up the page in the token manager: description, image, links, socials.
+- A one-time-fee token isn't tradable until the creator adds liquidity.
+- Launchpad trading fees build up in the pool. The creator claims them from **My Tokens**
+  (https://chaindaddy.io/_tokens), paying the network fee. Nothing is claimed automatically.
+- Keep it healthy: below 60 for 30 days in a row and the registration expires (`check-token-health`).
+- Next: `add-crypto-to-your-game` to sell items for it.
+
+## Mistakes to avoid
+
+- Sending the launch, a dev-buy or a fee claim yourself, even when an API key would let you. Hand it over.
+- Quoting fees, prices or chain support from memory instead of the live endpoints above.
+- Calling a token "an investment", promising returns, or predicting price.
+- Quoting a launch on several chains without each chain's own fee and network fee.
+- Forgetting the one-way doors in step 3.
+
+## Docs
+
+- https://docs.chaindaddy.io/launchpad
+- https://docs.chaindaddy.io/getting-started/create-a-token
+- https://docs.chaindaddy.io/api-reference/cli#launchpad