@chaindaddy/mcp 0.4.2 → 0.6.0

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

package/skills/sell-items-in-your-app/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: sell-items-in-your-app
+description: Run a Chain Daddy creator store - open it, add items priced in a token or in dollars, create orders from your server, have the buyer's wallet pay, wait for confirmed, deliver, read and spend what a wallet owns, drops and rewards, webhooks, refunds - and test the whole loop on a no-money test store first. Use when someone wants to sell credits, skins, passes or badges for their token, give items away, or unlock perks for holders.
+license: MIT
+---
+
+# Sell items in your app
+
+A store sells **items** for one token. The buyer's wallet pays the token's payout wallet directly, in one
+on-chain transaction; the checkout contract has no owner and holds no balance. Once the payment confirms,
+Chain Daddy grants the item and signs a receipt. Items live off chain: they can't be transferred or cashed out.
+
+## Tools
+
+| Step | MCP (local server) | CLI (`npm i -g @chaindaddy/cli@beta`) | HTTP (`https://api.chaindaddy.io`) |
+|---|---|---|---|
+| Open the store | `iap_open_store` | `chaindaddy iap store open --chain base --crown 8` | `POST /api/v2/iap/stores` |
+| Test store | `iap_open_test_store` | `chaindaddy iap store test <storeId>` | `POST /api/v2/iap/stores/{id}/test-store` |
+| Items | `iap_create_sku`, `iap_update_sku`, `iap_list_skus` | `chaindaddy iap sku create/update/archive` | `/api/v2/iap/stores/{id}/skus` |
+| Server key | `iap_create_store_key` | `chaindaddy iap key create` | `POST /api/v2/iap/stores/{id}/keys` |
+| Orders | `iap_create_order`, `iap_get_order`, `iap_test_pay` | `chaindaddy iap order create/show/test-pay` | `POST /api/v2/iap/orders` |
+| What a wallet owns | `iap_get_entitlements`, `iap_consume`, `iap_grant`, `iap_revoke` | `chaindaddy iap entitlements/consume/grant/revoke` | `/api/v2/iap/stores/{id}/entitlements` |
+| Rewards | `iap_create_drop`, `iap_set_drop_status`, `iap_award` | `chaindaddy iap drop …` | `/api/v2/iap/stores/{id}/drops` |
+| Events | `iap_list_events`, `iap_set_webhook`, `iap_test_webhook` | `chaindaddy iap events/webhook …` | `/api/v2/iap/stores/{id}/events` |
+
+Credentials: account calls (open a store, manage items and keys) use the human's `chaindaddy login` on this
+computer (or a `cd_live_…` key in `CHAINDADDY_API_KEY` on a server). The game server uses a **store key** `cd_iap_…` from `CHAINDADDY_IAP_KEY`: one store,
+only its scopes, sent alone as `Authorization: Bearer`. The plan gate: Developer, Partner or Enterprise, or
+Developer Beta Program membership; otherwise every call answers `403 IAP_PLAN_REQUIRED` - stop and tell the human.
+
+## Steps
+
+1. **Open the store** with the token page's chain key and crown id. Opening again returns the same store.
+   Report `id`, `payoutAddress` (starts as the owner's wallet), and `feeBps` (0 on a token launched in a Chain
+   Daddy launchpad pool, 250 otherwise).
+2. **Add items.** New items are `draft`; set `status: "active"` to list one. Create reward-only items (no
+   price, like `credits`) before the bundles that `grants` them. Example credit pack:
+   ```json
+   { "sku": "credits.100", "type": "consumable", "name": "100 credits",
+     "priceUsdMicros": 5000000, "minPrice": "1000000000000000000000",
+     "grants": [{ "sku": "credits", "quantity": 100 }], "status": "active" }
+   ```
+   `sku`: lowercase letters, digits, `.`, `_`, `-`, up to 64. A fixed `price` is a **base-unit string**
+   (5,000 tokens at 18 decimals = `"5000000000000000000000"`). An item has `price` or `priceUsdMicros`, not
+   both. `currency` is `token` (default), `native` or `usdc`. Confirm human-readable amounts with the human.
+3. **Make a store key** with only the scopes the server needs, typically `orders:read orders:write
+   entitlements:read entitlements:write`. The secret is shown **once**: tell the human to store it as
+   `CHAINDADDY_IAP_KEY` in their secrets manager. Never print it back.
+4. **Test it** (next section) before any live sale.
+5. **Server creates the order** for the user's wallet, with `appAccountToken` = your own user id and an
+   `Idempotency-Key` per purchase attempt (your cart id). It locks the price for about 20 minutes (5 for a
+   dollar price paid in the token or coin).
+6. **Client pays** from the order's `payment` block, as given. EVM: send `calls.approve` (when present), wait
+   for it, then `calls.pay`; or sign `permitTypedData` and call `payWithPermit`. Solana: the wallet signs and
+   sends `payment.transaction`. The client never computes an amount.
+7. **Wait for `confirmed`.** Poll the order, or listen for `iap.order.confirmed`. Optionally
+   `POST /api/v2/iap/orders/{id}/submit` with `{"txHash": …}` to check at once.
+8. **Deliver.** Verify the receipt (`verify-receipts-and-sessions`), then grant; or read the item ledger and
+   spend with `consume` (with an idempotency key).
+
+On a token page, a Crown App skips steps 5-7: it declares `iap:purchase` and sends
+`onAction({ type: 'iap-purchase', sku, quantity })`; the page runs the sale (see `build-a-crown-app`).
+
+A Crown App can also spend the viewer's own consumable with no server: it declares `iap:consume` and sends
+`onAction({ type: 'iap-consume', sku, quantity, key })` from the viewer's tap. It works only for an item whose
+`maxAppSpend` the store's owner set (the most an app may spend per request; null means no app can), and it is
+never proof: a holder can make that spend without the app. Keep `maxAppSpend` null and spend with `consume`
+on your server for anything competitive or redeemed for a prize.
+
+## Test store first
+
+Available where `GET /api/v2/iap/config` answers `"testMode": true`.
+
+1. `iap_open_test_store` with the **live** store id. It copies the live catalog once; after that they are separate.
+2. `iap_create_store_key` on the **test** store id. Its secret starts `cd_iap_test_`.
+3. Create an order with the test key; its `payment` is `{"kind":"test"}`.
+4. `iap_test_pay` (`POST /api/v2/iap/orders/{id}/test-pay`): the order confirms through the real path. No
+   chain, no money, no fee.
+5. The receipt and webhooks carry `"livemode": false`. Give the test store its own webhook.
+6. Go live by switching to the live key. Token prizes and claim links don't run on a test store.
+
+## Rewards and webhooks
+
+- One-off gift: `iap_grant`. A drop: `iap_create_drop` with `mode` `claim` (a link), `push` (a wallet list),
+  or `award` (your server awards a wallet with `iap_award`, scope `rewards:award`). Drops start as drafts.
+- Webhook: `iap_set_webhook` with a public `https://` URL; the `whsec_…` secret is shown once. Check
+  `X-Webhook-Signature` (hex HMAC-SHA256 of the raw body) before parsing. Answer 2xx within 5 seconds.
+- Reconcile from the event feed (`iap_list_events` with `after` = your last event id). The webhook makes you
+  fast; the feed makes you complete.
+- Refunds: the creator sends the money back from their wallet, then records it with `iap_refund_order`
+  (`refund_tx_hash`; CLI `--tx`), which revokes the items and receipt. Chain Daddy cannot move a buyer's funds.
+
+## Mistakes to avoid
+
+- Granting on `paid`, or before verifying the receipt's signature, `storeId` and `livemode`.
+- A store key in the game client. Only the server holds it.
+- Retrying a write with a new idempotency key: it can sell or grant twice. Reuse the same key.
+- Editing the `payment` block, or paying in another currency: the payment is recorded as `order.mismatch`
+  and grants nothing.
+- Treating `503 PRICE_UNAVAILABLE` as a failure: the dollar price can't be converted right now; retry in a minute.
+- Items with a random outcome (loot boxes): not allowed. Never call items money or a balance.
+- Sending a payment for the human. They pay from their own wallet.
+
+## Docs
+
+- https://docs.chaindaddy.io/developer/store-and-rewards (every field, rule, event and limit)
+- https://docs.chaindaddy.io/developer/test-your-integration
+- OpenAPI: https://docs.chaindaddy.io/openapi.yaml, tag **Creator Store**

package/skills/sign-in-with-chain-daddy/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: sign-in-with-chain-daddy
+description: Add "Sign in with Chain Daddy" to a website, game or app - standard OpenID Connect (authorization code + PKCE, ES256 ID tokens) that tells your server which wallet the visitor controls. Covers registering a client, the stock-library setup, the claims to check, and how it differs from a Crown App session token. Use when someone wants wallet sign-in, "log in with Chain Daddy", or to link a player account to a wallet.
+license: MIT
+---
+
+# Sign in with Chain Daddy
+
+The visitor goes to chaindaddy.io, approves your site, and comes back with an ID token that says **which
+wallet they control**. It is standard OpenID Connect, so use a stock library (openid-client, Auth.js,
+go-oidc, Authlib, Spring Security, .NET). You get an ID token and nothing else: no refresh token, no access
+to the Chain Daddy API for the user, no email, no balance. Keep your own session afterwards.
+
+## Endpoints
+
+Use discovery: `https://api.chaindaddy.io/.well-known/openid-configuration`
+
+| | |
+|---|---|
+| Issuer | `https://api.chaindaddy.io` |
+| Authorize (consent page) | `https://chaindaddy.io/_oauth/authorize` |
+| Token | `https://api.chaindaddy.io/api/v2/oauth/token` |
+| Keys | `https://api.chaindaddy.io/api/v2/oauth/jwks` |
+
+## 1. Register a client (the human does this)
+
+Needs Developer Beta Program membership (free to register). Easiest: the developer portal,
+https://chaindaddy.io/_developer → **Sign-in** → **New client**. Or:
+
+```bash
+chaindaddy oauth client create --name "My Game" \
+  --redirect-uri https://example.com/auth/callback --confidential --crown base:8
+```
+
+API: `POST https://api.chaindaddy.io/api/v2/developer/oauth-clients` with the human's `cd_live_…` key.
+
+- `redirectUris` match **exactly**: no wildcards. `https` only, except `http://localhost` and
+  `http://127.0.0.1` for development.
+- `confidential: true` for a server that keeps a secret (`cd_oauth_…`, shown once - the human stores it).
+  A single-page app, game client or native app stays public and uses PKCE with no secret.
+- `name`: up to 40 characters, and may not contain "Chain Daddy", "official", "support" or "wallet".
+- `crown` (optional) earns the consent screen's **verified** mark when the human manages that token page
+  and the redirect host is one of the page's verified domains.
+
+## 2. Wire the flow
+
+Node, with openid-client:
+
+```ts
+import * as client from 'openid-client';
+
+const config = await client.discovery(
+  new URL('https://api.chaindaddy.io'), process.env.CD_CLIENT_ID!,
+  { id_token_signed_response_alg: 'ES256' },
+  client.ClientSecretPost(process.env.CD_CLIENT_SECRET!), // client.None() for a public client
+);
+
+// Sign-in: keep verifier, state and nonce in the visitor's session
+const verifier = client.randomPKCECodeVerifier();
+const state = client.randomState();
+const nonce = client.randomNonce();
+const url = client.buildAuthorizationUrl(config, {
+  redirect_uri: 'https://example.com/auth/callback', scope: 'openid wallets',
+  code_challenge: await client.calculatePKCECodeChallenge(verifier), code_challenge_method: 'S256',
+  state, nonce,
+});
+
+// Callback
+const tokens = await client.authorizationCodeGrant(config, new URL(req.url, 'https://example.com'), {
+  pkceCodeVerifier: verifier, expectedState: state, expectedNonce: nonce,
+});
+const claims = tokens.claims()!;
+if (claims.typ !== 'signin+v1') throw new Error('not a Chain Daddy sign-in');
+const wallet = claims.sub; // start your own session for this wallet
+```
+
+Auth.js: a provider with `type: 'oidc'`, `issuer: 'https://api.chaindaddy.io'`,
+`checks: ['pkce', 'state', 'nonce']`, `client: { id_token_signed_response_alg: 'ES256' }`, and a `profile()`
+that throws unless `typ === 'signin+v1'`.
+
+## Scopes and claims
+
+| Scope | Adds |
+|---|---|
+| `openid` (required) | `sub` (the wallet: lowercase hex on EVM, base58 on Solana), `chain` (`evm` or `solana`) |
+| `wallets` | `wallets`: every wallet linked to the account, `sub` first |
+| `profile` | `identity`: the handle they chose to publish |
+
+Check on every ID token: signature (ES256, keys above), `iss` = `https://api.chaindaddy.io`, `aud` = your
+client id, `typ` = `signin+v1`, `nonce` = the one you sent, `exp` (5 minutes).
+
+## After sign-in
+
+Gate on what the wallet owns live, on your server: your store's
+`GET /api/v2/iap/stores/{id}/entitlements?wallet=<sub>` (holder unlocks included). Never put a balance in
+your session: it goes stale in minutes.
+
+## Crown Apps use something else
+
+Inside a Crown App on a token page, use the `session-token` action (an `app-session+v1` token, EdDSA, keys
+at `/api/v2/apps/jwks`). If your site and your Crown App share a server, verify both kinds and key people by
+`sub`: it is the same wallet string in both. See `verify-receipts-and-sessions`.
+
+## Mistakes to avoid
+
+- Skipping PKCE (`S256`) or `state`: both are required on every request.
+- Not checking `typ`. A token of another kind must never pass for a sign-in.
+- Expecting a refresh token or API access: there is neither. A returning visitor who approved before signs
+  in again without a click.
+- Redirect URIs that differ by a slash or a port: they must match exactly, or chaindaddy.io refuses.
+- Putting the client secret in a browser, game client or repo.
+- Asking the visitor to sign a second login message in their wallet. This is the sign-in.
+
+## Docs
+
+https://docs.chaindaddy.io/developer/sign-in-with-chain-daddy

package/skills/verify-receipts-and-sessions/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: verify-receipts-and-sessions
+description: Verify what Chain Daddy signs on your own server before acting on it - store purchase receipts (iap-receipt+v1), Crown App session tokens (app-session+v1), Sign in with Chain Daddy ID tokens (signin+v1), and webhook signatures - with the exact keys, claims and checks, plus published test vectors. Use when writing server code that grants items, credits a purchase, trusts a player's wallet, or receives Chain Daddy webhooks.
+license: MIT
+---
+
+# Verify receipts, sessions and webhooks
+
+Never act on something because a client sent it. Each kind below has its own keys and its own `typ` claim,
+so one can never pass for another - as long as you check `typ`.
+
+## Which token is which
+
+| You have | `typ` claim | Algorithm | `iss` | Keys (JWKS) | Also check |
+|---|---|---|---|---|---|
+| Store receipt (a confirmed purchase) | `iap-receipt+v1` | EdDSA (Ed25519) | `https://chaindaddy.io` | `https://api.chaindaddy.io/api/v2/iap/jwks` | `storeId` is your store; `livemode` is `true` in production; credit each `orderId` once |
+| Crown App session token (`session-token` action) | `app-session+v1` | EdDSA | `https://chaindaddy.io` | `https://api.chaindaddy.io/api/v2/apps/jwks` | `aud` is your app id (`<developerId>/<name>`); `exp` (5 min, allow 30 s skew); refuse a `jti` you have seen; `idv === true` if you need a verified person |
+| Sign in with Chain Daddy ID token | `signin+v1` | ES256 | `https://api.chaindaddy.io` | `https://api.chaindaddy.io/api/v2/oauth/jwks` | `aud` is your client id; `nonce`; `exp` (5 min) |
+
+Notes:
+- The JWS **header** `typ` is a plain `JWT`. What the token is lives in the `typ` **claim**. Check the claim.
+- Pick the key by the header's `kid`. Each set lists the current key first and keeps the previous one, so a
+  cached remote key set that refetches on an unknown `kid` survives rotation with no work.
+- `sub` is the wallet in all three: lowercase `0x…` on EVM, base58 on Solana.
+
+## TypeScript (jose)
+
+```ts
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+
+const API = 'https://api.chaindaddy.io';
+const ISSUER = 'https://chaindaddy.io';
+const receiptKeys = createRemoteJWKSet(new URL('/api/v2/iap/jwks', API));
+const sessionKeys = createRemoteJWKSet(new URL('/api/v2/apps/jwks', API));
+
+export async function verifyReceipt(jws: string, storeId: string) {
+  const { payload } = await jwtVerify(jws, receiptKeys, { algorithms: ['EdDSA'], issuer: ISSUER });
+  if (payload.typ !== 'iap-receipt+v1') throw new Error('not a store receipt');
+  if (payload.storeId !== storeId) throw new Error('receipt is for another store');
+  if (payload.livemode === false && process.env.NODE_ENV === 'production') throw new Error('test receipt');
+  return payload; // grant by payload.sku, payload.quantity, payload.wallet; dedupe on payload.orderId
+}
+
+export async function verifySession(token: string, appId: string) {
+  const { payload } = await jwtVerify(token, sessionKeys, {
+    algorithms: ['EdDSA'], issuer: ISSUER, audience: appId, clockTolerance: 30,
+  });
+  if (payload.typ !== 'app-session+v1') throw new Error('not an app session token');
+  if (!payload.exp) throw new Error('no expiry');
+  return payload; // payload.sub is the wallet; check payload.idv === true to require a verified person
+}
+```
+
+For the ID token, use your OpenID Connect library (see `sign-in-with-chain-daddy`), or `jwtVerify` with the
+oauth key set, `issuer: 'https://api.chaindaddy.io'`, `audience: <client id>`, `algorithms: ['ES256']`, then
+check `typ === 'signin+v1'` and the nonce. Go: `server/cdapi` in https://gitlab.com/opencrown/flux-gp-kit.
+
+## Refunds: offline is not enough for everything
+
+An offline receipt check can't see a refund made since. For anything that matters after the fact, also check
+online - `POST https://api.chaindaddy.io/api/v2/iap/receipts/verify` with `{"receipt": "…"}` returns
+`valid` or `revoked` - or read the store's item ledger (`GET …/entitlements?wallet=`), which is the source of
+truth for what a wallet owns now.
+
+## Webhook signatures
+
+| Webhook | Header | How to check |
+|---|---|---|
+| Store webhook (`iap.*`) | `X-Webhook-Signature` | Hex HMAC-SHA256 of the **raw body**, keyed with the `whsec_…` secret as given |
+| Crown App runner events | `X-App-Signature` | Hex HMAC-SHA256 of the raw body, keyed with the runner secret **hex-decoded to bytes** |
+
+```js
+import crypto from 'node:crypto';
+function verifyStoreWebhook(rawBody, signature, secret) {
+  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
+  return signature?.length === expected.length &&
+    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+}
+```
+
+Check against the raw bytes before parsing JSON, compare in constant time, and ignore a repeated event `id`
+(retries reuse it). Answer 2xx within 5 seconds.
+
+## Prove your checker with the test vectors
+
+https://docs.chaindaddy.io/vectors/tokens.json holds two key sets (`jwks.session`, `jwks.receipts`), a fixed
+`now`, an `appId`, a `storeId` and 15 tokens marked `valid` or not (expired, clock skew, another app, another
+issuer, `typ` only in the header, no expiry, a forgery, a receipt offered as a session and the reverse,
+another store). Load the sets with `createLocalJWKSet`, run every case at `now`, and pass only when your
+code accepts exactly the valid ones. Add this as a unit test.
+
+## Mistakes to avoid
+
+- Checking the header `typ` instead of the claim, or not checking `typ` at all.
+- Verifying a session token against the receipt keys, or the other way round: they use different key sets.
+- Using `iss: https://api.chaindaddy.io` for receipts and sessions. Only Sign in ID tokens use the `api.` issuer.
+- Accepting a test receipt (`livemode: false`) or another store's receipt in production.
+- Crediting the same `orderId` twice when the webhook and your poller both see it.
+- Parsing the webhook body before checking its signature, or comparing with `===`.
+- Treating a session token as API access: it only proves presence to your server.
+
+## Docs
+
+- https://docs.chaindaddy.io/developer/verifying-tokens
+- https://docs.chaindaddy.io/developer/store-and-rewards#verifying-receipts-on-your-server
+- https://docs.chaindaddy.io/developer/security#session-tokens