@moonpay/cli 1.49.1 → 1.51.0

package/skills/moonpay-automation-builder/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: moonpay-automation-builder
+description: Author new automations for the MoonPay Agents app. Use when the user wants to schedule a recurring task — a daily portfolio email, an hourly price check, a weekly rebalance, a cron-triggered prompt. Automations are JSON entries that fire a prompt or skill on a cron schedule via either the Claude Code or Codex backend. This skill defines the JSON schema, where to write it, and how to pick a sensible cron.
+---
+
+# MoonPay Automation Builder
+
+An automation is a saved prompt that the MoonPay Agents app fires on a cron schedule. The first fire spawns a fresh agent session; every subsequent fire `--resume`s the same session so the agent keeps its memory across runs. This is how "every morning, summarize my portfolio" or "every Monday at 9am, run my DCA strategy" actually run.
+
+This skill is how new automations get authored.
+
+## When to use this skill
+
+- The user wants something to run on a schedule, not just one-shot.
+- The user already has a skill or a prompt that works once and wants to run it on repeat.
+- The user describes the trigger with words like "every day", "every Monday", "hourly", "twice a week", "at 9am".
+
+If the user wants a one-shot future action ("remind me at 3pm"), suggest the `schedule` skill instead — that's cloud-side and one-time.
+
+## On-disk format
+
+All automations live in a single file:
+
+```
+~/.moonpay-agents/automations.json
+```
+
+It's a JSON array of automation objects. Each object:
+
+```json
+{
+  "id": "<uuid v4>",
+  "name": "Morning portfolio check",
+  "body": "Run mp portfolio retrieve --json, summarize the top movers since yesterday, and Slack me a 3-bullet update.",
+  "cron": "0 9 * * *",
+  "backend": "claude",
+  "enabled": true,
+  "sessionId": null,
+  "lastRun": null,
+  "lastStatus": null,
+  "lastOutput": null,
+  "createdAt": "2026-05-14T17:00:00Z"
+}
+```
+
+| field | required | notes |
+|---|---|---|
+| `id` | required | UUID v4. Generate one if creating new. |
+| `name` | required | Short label shown in the Automations view. |
+| `body` | required | The prompt the agent runs on each fire. Write it like a normal user message — the agent sees this verbatim. |
+| `cron` | required | 5-field cron: `min hour dom month dow`. See "Picking a cron" below. |
+| `backend` | required | `"claude"` or `"codex"`. Default to `"claude"` unless the user prefers Codex. |
+| `enabled` | optional | Defaults to `true`. Set `false` to author the automation without firing it. |
+| `sessionId` | optional | Leave `null` — the app fills this in after the first fire. |
+| `lastRun`, `lastStatus`, `lastOutput` | optional | Leave `null` — written by the app after each fire. |
+| `createdAt` | required | ISO-8601 timestamp. Use the current time. |
+
+The app reloads `automations.json` on every save, so writing directly to disk works — no IPC needed.
+
+## Picking a cron
+
+The format is the standard 5-field Unix cron: `minute hour day-of-month month day-of-week`. **Day-of-week is 0–6 with 0 = Sunday.**
+
+| Cadence | Cron | Notes |
+|---|---|---|
+| Every minute | `* * * * *` | Don't. Almost always a bug. |
+| Every 5 minutes | `*/5 * * * *` | Polling. Fine for cheap checks. |
+| Every hour on the hour | `0 * * * *` | |
+| Daily at 9am | `0 9 * * *` | Local time of the device running the app. |
+| Every weekday at 9am | `0 9 * * 1-5` | Mon–Fri. |
+| Every Monday at 9am | `0 9 * * 1` | |
+| First of the month at 9am | `0 9 1 * *` | |
+
+The MoonPay Agents app uses a 6-field internal form (`sec min hour dom month dow`) — it prepends `0 ` automatically. Always write 5-field cron in the JSON.
+
+### Cron gotchas
+
+- **Day-of-month + day-of-week are OR'd**, not AND'd. `0 9 1 * 1` fires on the 1st of the month AND every Monday — usually not what people want.
+- **App must be running.** The scheduler is in-process; if the app is closed, the automation doesn't fire. (No launchd integration today.)
+- **Time zone** = local machine time. If the user moves time zones, the cron fires at the same local time, not the same UTC time.
+
+## Writing the `body`
+
+The body is the prompt the agent gets on every fire. Two things to get right:
+
+### 1. Write it like a normal user message
+
+```
+Pull my Polymarket positions with mp polymarket positions list --json. For each position
+where the current price has moved >5% from entry, draft a Slack message to #me with the
+position name, entry price, current price, and PnL.
+```
+
+Not:
+
+```
+Execute polymarket position summary procedure
+```
+
+The agent reads the body the same way it reads a chat message. Be specific about what data to pull, what to do with it, and where to deliver the result.
+
+### 2. Don't recreate skills inline
+
+If the workflow already exists as a skill (`mp skill list`), invoke the skill instead of describing its steps:
+
+> "Use the moonpay-portfolio skill. Compute drift from my target allocation and Slack me a one-line summary if drift > 5%."
+
+This keeps the automation small and lets skill improvements propagate automatically.
+
+### 3. Pick the right backend
+
+- **`"claude"`** for anything that needs nuanced judgment, web research, or long-form output. Default.
+- **`"codex"`** if the workflow is heavily code-modifying (e.g. "regenerate this report HTML and write it to disk") and you want Codex's editing harness.
+
+## Authoring flow (what the agent should do)
+
+When the user invokes you:
+
+1. **Ask three things**:
+   - What should this automation do? (the body)
+   - How often? (the cron — in plain English, you'll convert)
+   - Backend? (default to claude unless they specify)
+2. **Convert the cadence to a 5-field cron** and read it back to the user in plain English ("Every weekday at 9am — `0 9 * * 1-5`") to confirm.
+3. **Read `~/.moonpay-agents/automations.json`** (create the file as `[]` if missing).
+4. **Append a new automation object** with a freshly generated UUID v4, the current ISO-8601 timestamp for `createdAt`, the user's body, the cron, the backend, `enabled: true`, and `null` for `sessionId`/`lastRun`/`lastStatus`/`lastOutput`.
+5. **Write the updated array back** to `~/.moonpay-agents/automations.json`. Pretty-print (2-space indent) — the user may edit it by hand.
+6. **Tell the user**: when the next fire is, the name + cron, and that they can disable/edit it from the Automations view.
+
+## Important rules
+
+- **Never write to `automations.json` without reading it first.** Read → modify → write. Don't blow away other automations.
+- **Always use UUID v4 for `id`** — incrementing IDs collide on import/export.
+- **Use `null`, not `""` or `undefined`**, for the lifecycle fields the app fills in (`sessionId`, `lastRun`, etc).
+- **Don't enable an automation that fires every minute** without warning the user. `*/5 * * * *` is usually the right floor.
+- **Validate the cron** by running it through `cron --validate <expr>` or noting in the response that the app's scheduler will reject invalid expressions on save.
+
+## Common pitfalls
+
+- **Cron means local time.** Users who travel get surprises. Mention it on creation if the cadence is time-sensitive.
+- **First fire is at the next match.** A 9am daily automation created at 10am won't fire until 9am tomorrow. Tell the user the expected next-fire time.
+- **Body is too vague.** "Check my portfolio" produces wildly different output each fire. "Run mp portfolio retrieve --json and Slack me a 3-bullet summary of changes since yesterday" produces consistent output.
+- **App-closed silence.** If a user complains an automation didn't fire, first thing to check: was the app actually running at the scheduled time?
+
+## Related
+
+- **moonpay-skill-builder** — author the underlying skill before scheduling it. Most good automations are "run this skill on a cron".
+- **moonpay-artifact-builder** — for visual recurring reports, pair an automation that updates a JSON file with an artifact that reads it.
+- **`schedule` skill** (cloud-side) — for one-shot future runs ("at 3pm tomorrow, do X"). Different system, persists across app closure.

package/skills/moonpay-card-onboarding/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: moonpay-card-onboarding
+description: Set up a MoonAgents Card from scratch — collect identity, run KYC via Veriff, accept Baanx's Terms + Privacy + E-Sign disclosures, finalize registration, and delegate a Solana wallet for USDC spending. The conversational counterpart to the moon-agents-card Artifact's "Get started" CTA. Run this before moonpay-card-checkout if `mp card retrieve` errors with "No MoonCard account" or if the user has no delegated wallets.
+---
+
+# MoonAgents Card Onboarding
+
+## Goal
+
+Walk the user from "I want a MoonAgents Card" to "I can tap-to-pay on Solana USDC." This is a multi-step flow with real KYC, real legal acceptance, and a real on-chain delegation transaction. Don't shortcut any of it.
+
+The Artifact (**moon-agents-card** in the MoonPay Agents desktop app) routes here via "Get started" or "Delegate wallet" CTAs depending on which stage the user is in.
+
+## Pre-flight — figure out which stage they're at
+
+Always run these two probes first. The answers tell you where to pick up:
+
+```bash
+mp card retrieve --json
+mp card onboarding check --json
+```
+
+Five possible states:
+
+| State | Detected by | Jump to step |
+|---|---|---|
+| Never started | `mp card retrieve` errors "No MoonCard account" + `mp card onboarding check` errors with same | **Step 1** |
+| KYC in progress | `mp card onboarding check` returns `veriffUrl` (no `terms` block) | **Step 2** |
+| KYC verified, terms not accepted | `check` returns `terms: { termsAndConditions, privacyPolicy, eSignConsentDisclosure }` | **Step 3** |
+| Card created, no delegation | `mp card retrieve` succeeds, `mp card wallet list` is empty | **Step 4** |
+| Fully ready | both succeed and `mp card wallet list` returns items | **Done** — route to `moonpay-card-checkout` |
+
+Surface the current stage to the user so they understand where they are.
+
+## Step 1 — Collect identity details and start onboarding
+
+Ask the user for the required fields **one batch at a time** (don't drip out one field per turn — copy-paste-friendly):
+
+```
+- First name
+- Last name
+- Date of birth (YYYY-MM-DD)
+- Country of residence (ISO 3166-1 alpha-2, e.g. US, GB, DE)
+- Country of nationality (same format)
+- Phone country code (numeric, e.g. 1 for US, 44 for UK)
+- Phone number (digits only)
+```
+
+`mp user retrieve --json` may give you their email and name already — use that to pre-fill if available, but always read back to the user for confirmation.
+
+Then call:
+
+```bash
+mp card onboarding start \
+  --firstName "<first>" \
+  --lastName "<last>" \
+  --dateOfBirth "<YYYY-MM-DD>" \
+  --countryOfResidence "<XX>" \
+  --countryOfNationality "<XX>" \
+  --phoneCountryCode <code> \
+  --phoneNumber "<digits>"
+```
+
+Returns a Veriff KYC session URL. Surface it to the user with a click-through call to action ("Open this URL to complete identity verification: …"). The user opens it in their browser, completes Veriff's webcam + ID flow, comes back.
+
+`mp card onboarding start` is **idempotent** — safe to call again with the same fields if the user lost the URL or the session expired. It just returns a fresh URL.
+
+## Step 2 — Poll for KYC verification
+
+After the user comes back, run:
+
+```bash
+mp card onboarding check --json
+```
+
+Three things can come back:
+- Still pending → `veriffUrl` again, no `terms` block. Tell the user Veriff hasn't reported back yet, wait 30s, re-check.
+- **Rejected** → check response will indicate failed status. Direct the user to retry the Veriff session (a fresh `mp card onboarding start` returns a new URL).
+- **Verified** → response contains a `terms` block. Jump to Step 3.
+
+Don't auto-poll in a tight loop — KYC takes minutes, not seconds. One check, surface status, ask the user to nudge you again when they're done.
+
+## Step 3 — Show terms, collect address, finalize
+
+The `check` response contains live URLs Baanx records consent against. **Never hardcode legal URLs** — fetch them fresh each time and surface them to the user:
+
+```
+terms.termsAndConditions       — Baanx Terms of Service
+terms.privacyPolicy             — Privacy Policy
+terms.eSignConsentDisclosure    — US-only E-Sign Act Disclosure
+```
+
+Show all three URLs to the user. Ask them to open each, read, and confirm they accept. Don't paraphrase the legal text — the URLs the user sees must match what Baanx records consent against.
+
+Then ask for shipping/billing address:
+```
+- Address line 1
+- Address line 2 (optional)
+- City
+- ZIP / postal code
+```
+
+Then finalize:
+
+```bash
+mp card onboarding finish \
+  --addressLine1 "<address>" \
+  --addressLine2 "<line2 or omit>" \
+  --city "<city>" \
+  --zip "<zip>" \
+  --acceptTerms true \
+  --acceptESign true       # only for US residents; omit otherwise
+```
+
+On success, the user has a Baanx-issued virtual card. `mp card retrieve` now works. Move to Step 4.
+
+## Step 4 — Delegate a Solana wallet
+
+The card pulls USDC from a Solana wallet the user explicitly delegates. Two things to collect:
+
+1. **Which local wallet** — `mp wallet list` to see options. Most users have one (e.g. `main`). If they don't, run `mp wallet create --name main --chain solana` first.
+2. **Spending cap** — the on-chain `approve` amount. User-controlled. Recommend `500` for a starter cap; they can re-link with a higher cap later. **Don't suggest unlimited** — the cap is the blast radius if Baanx is ever compromised.
+
+```bash
+mp card wallet link --wallet <name> --currency USDC --amount <cap>
+```
+
+This runs the 4-step dance locally: builds an SPL Approve tx, signs + broadcasts, fetches a fresh token+nonce from Baanx, signs the SIWS ownership message, registers with Baanx. The user sees the tx in their Solana wallet history.
+
+On success, `mp card wallet list` shows the delegation. The user is fully onboarded.
+
+## Wrap-up
+
+Tell the user they're done and what's possible now:
+
+> "You're set. Your MoonAgents Card is live with `$<cap>` delegated from your `<wallet>` Solana wallet. Tap the **Start shopping** button on the MoonAgents Card artifact whenever you want to spend it — it'll route through me and the **moonpay-card-checkout** skill."
+
+## Important rules
+
+- **Never hardcode the Veriff URL or legal URLs** — always fetch fresh from `mp card onboarding check`
+- **Never auto-accept terms** — the user must see all three URLs and explicitly agree
+- **Never suggest an unlimited delegation cap** — the cap is the loss ceiling if anything goes wrong
+- **Never store the user's PII anywhere** — once you've passed it to `mp card onboarding start/finish`, drop it
+- **Idempotency**: `mp card onboarding start` and `finish` are safe to retry with the same arguments — useful when sessions time out
+
+## Related
+
+- **moonpay-card-checkout** — runs purchases once onboarding is done. Routes back here if state regresses (e.g., delegation expired).
+- **moon-agents-card** (Artifact) — visual state. Shows "Get started" / "Delegate wallet" / ready states based on what `mp card retrieve` + `mp card wallet list` return.
+- **moonpay-auth** — if `mp` isn't logged in, the user needs to handle that first.

package/skills/moonpay-skill-builder/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: moonpay-skill-builder
+description: Author new agent skills for the MoonPay Agents app. Use when the user wants to teach the agent a new workflow, encode a procedure they keep repeating, or wrap a CLI sequence as a single invokable skill. Skills are markdown files with YAML frontmatter that both Claude Code and Codex pick up natively. This skill defines the contract, the save location, and how to write skills that don't suck.
+---
+
+# MoonPay Skill Builder
+
+A skill is a markdown file the agent reads when it decides the user's request matches the skill's description. It's not a function call — it's an instruction set the agent follows. Used well, skills turn a 12-step chat into one prompt; used badly, they're just untested documentation.
+
+This skill is how new skills get authored.
+
+## When to use this skill
+
+- The user has a procedure they've walked the agent through more than twice.
+- The user wants to share an agent workflow with their team.
+- The user wants to wrap a `mp` CLI command sequence (or any other tool sequence) as a single invocable thing.
+
+Don't use this skill for one-off requests or things that are already a single `mp` command — those don't need a skill.
+
+## On-disk format
+
+A skill is a directory. The directory name is the skill slug (kebab-case, must match the frontmatter `name`).
+
+```
+<slug>/
+├── SKILL.md          # Required. Frontmatter + body.
+├── scripts/          # Optional. Helper scripts the skill body calls.
+├── references/       # Optional. Long-form docs the body links to.
+└── templates/        # Optional. Reference files the agent can read or copy.
+```
+
+Only `SKILL.md` is required. Most useful skills stop there.
+
+### `SKILL.md` frontmatter
+
+Both Claude Code and Codex are strict — only **two fields** are portable across both engines:
+
+```yaml
+---
+name: my-skill-slug
+description: One paragraph explaining (a) WHEN the agent should invoke this skill, and (b) WHAT it does. The description is the matching surface — write it like a router, not a summary.
+---
+```
+
+| key | required | notes |
+|---|---|---|
+| `name` | required | kebab-case slug, matches the directory name |
+| `description` | required | The matching text. See "Writing the description" below — this is the highest-leverage part of the skill |
+
+**Do not add other fields** (`tags`, `category`, `version`, `author`, etc). Codex's docs explicitly state "Do not include any other fields in YAML frontmatter." Claude has its own optional fields (`allowed-tools`, `disable-model-invocation`, `model`, `effort`, `paths`, etc.) but those are Claude-specific — using them breaks portability.
+
+For app-side metadata that the MoonPay Agents app might want (filter chips, icons, etc.), the app derives those from the skill's filesystem location, not from frontmatter. Built-in skills come from the plugin path; user-authored skills come from `.agents/skills/`. No metadata required from the skill itself.
+
+### Save location
+
+Write user-authored skills here:
+
+```
+~/.moonpay-agents/.agents/skills/<slug>/SKILL.md
+```
+
+(The `.agents/skills/` path is Codex-native. The MoonPay Agents app symlinks `.claude/skills` → `.agents/skills` on startup so Claude Code picks them up too.)
+
+Built-in MoonPay skills live under `~/.moonpay-agents/plugins/moonpay/skills/` and are managed by `mp plugin install/update` — don't write there.
+
+## Writing the description
+
+The description is the only thing the agent sees when deciding whether to invoke your skill. Write it like routing logic, not like documentation.
+
+**Good** (specific triggers, concrete verbs, says what it does):
+> Trade on Polymarket — search markets, buy/sell outcome shares, track positions and PnL. Use when the user names Polymarket explicitly, or wants politics, crypto, news, or general-events markets.
+
+**Bad** (vague, no trigger words):
+> Helps with prediction markets.
+
+**Bad** (says what NOT to do without saying what to do):
+> Don't use for Kalshi. Don't use for sports betting. Don't use for…
+
+A good description answers two questions in one paragraph:
+1. **When should the agent pick this skill?** (Specific triggers, user phrases, concrete situations.)
+2. **What will the agent do once it picks it?** (One verb-led sentence: "search…, buy/sell…, track…")
+
+If your description doesn't have at least two trigger phrases the user would actually say, rewrite it.
+
+## Writing the body
+
+The body is what the agent reads after picking the skill. It's read-only context, not executable — the agent decides what to actually do based on what the body says.
+
+### Structure that works
+
+```markdown
+# <Skill Title>
+
+One sentence: what this skill does and the one thing it's good for.
+
+## When to use
+
+Bullet list of concrete situations. Be specific. "When the user mentions X" beats "When relevant."
+
+## Setup (if any)
+
+Commands to run once before the skill's main flow. Skip the section entirely if there's no setup.
+
+## The flow
+
+Numbered steps. Each step:
+- States the goal of the step in one line
+- Shows the exact command(s) with example argv
+- Says what to surface to the user between steps
+
+## Important rules
+
+Bullets of must / never. Use these for things that look optional but aren't (e.g. "Always pass --json", "Never click Pay Now").
+
+## Related
+
+Links to other skills the agent should bounce to.
+```
+
+### Body rules
+
+- **Write commands literally**, with realistic example arguments. The agent will copy-paste them. `mp wallet list` is useful; `mp <whatever wallet command>` is not.
+- **Don't paraphrase tool output.** If the skill processes the output of `mp foo --json`, name the actual fields (`data.items[0].balance`, not "the balance field").
+- **Surface intermediate state to the user.** Between steps, the agent should tell the user what just happened in one line. Write that line in the skill body so the agent doesn't have to invent it.
+- **Pause for confirmation before irreversible actions** — send money, sign tx, push to remote, click Pay. Spell out the pause in the body.
+- **Bail to another skill** if pre-flight fails. Example: `moonpay-card-checkout` bails to `moonpay-card-onboarding` if there's no card yet.
+
+### Body anti-patterns
+
+- **"This skill is helpful for…"** — that's the description's job. The body is for the agent, not the user.
+- **Explaining concepts at length.** If you find yourself writing two paragraphs of background, move it to `references/<topic>.md` and link to it.
+- **Branching trees.** If the skill has 6 if/else paths, it's probably 2 skills.
+- **No examples.** Every command needs at least one concrete example argv.
+
+## Authoring flow (what the agent should do)
+
+When the user invokes you:
+
+1. **Ask what the skill should do** — one paragraph from the user describing the workflow, including the triggers ("when I say X").
+2. **Propose the slug + description back to the user** for confirmation. The description is the highest-leverage part; don't move past this until the user says yes.
+3. **Draft the body** following the structure above. Use real `mp` commands where possible — search `mp --help` if you're unsure.
+4. **Save** to `~/.moonpay-agents/.agents/skills/<slug>/SKILL.md` (create the directory if needed).
+5. **Show the user the saved path** and remind them they may need to restart the chat for the agent to pick up the new skill.
+
+## Common pitfalls
+
+- **Skill is too broad.** "moonpay-helper" with description "helps with MoonPay stuff" will never be selected reliably. Each skill should do one thing.
+- **Skill is too narrow.** "moonpay-buy-eth-on-monday" should just be an automation, not a skill.
+- **Skill description is the same as an existing skill.** Run `mp skill list` first; if there's overlap, edit the existing skill instead of adding a new one.
+- **Skill calls `mp` commands that don't exist.** Run them in a shell first to confirm flags + output shape.
+- **Skill body is a wall of prose.** The agent will read it, but the user won't review it. Keep it tight.
+
+## Related
+
+- **moonpay-artifact-builder** — sibling skill for authoring HTML artifacts (the visual side; this one is the procedural side).
+- **moonpay-automation-builder** — sibling skill for scheduling existing skills on a cron.
+- **`mp skill list`** — see what's already installed before authoring a new one.