@moonpay/cli 0.2.4 → 0.2.5

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@moonpay/cli",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
   "files": [
     "dist",
+    "skills",
     "README.md"
   ],
   "bin": {

package/skills/moonpay-auth/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: moonpay-auth
+description: Authenticate and manage local wallets with MoonPay CLI. Use when you need to log in, check auth state, or manage wallets for signing transactions.
+tags: [setup]
+---
+
+# MoonPay auth
+
+## Goal
+
+Set up authentication and local wallet management for the MoonPay CLI (`mp`).
+
+## Auth commands
+
+```bash
+# Log in (opens browser for OAuth)
+mp login
+
+# Check current user
+mp user retrieve
+
+# Log out
+mp logout
+```
+
+## Local wallet management
+
+The CLI manages local Solana wallets stored in `~/.config/moonpay/wallets/`. Private keys never leave the machine — transactions are signed locally.
+
+```bash
+# Create a new wallet
+mp wallet create --name "my-wallet"
+
+# Import from a base58 private key
+mp wallet import --name "imported" --privateKey <base58-key>
+
+# List all local wallets
+mp wallet list
+
+# Get wallet details (by name or address)
+mp wallet retrieve --wallet "my-wallet"
+mp wallet retrieve --wallet <address>
+
+# Delete a wallet (irreversible)
+mp wallet delete --wallet "my-wallet" --confirm
+```
+
+## Workflow
+
+1. Run `mp user retrieve` to check if authenticated.
+2. If it fails, run `mp login` (opens browser).
+3. Run `mp wallet list` to see local wallets.
+4. If no wallets, create one: `mp wallet create --name "default"`.
+
+## Notes
+
+- Credentials: `~/.config/moonpay/credentials.json`
+- Wallets: `~/.config/moonpay/wallets/`
+- Tokens auto-refresh on expiry. If refresh fails, run `mp login` again.
+
+## Related skills
+
+- **moonpay-env** — Environment and PATH setup.
+- **moonpay-swap-tokens** — Swap tokens using local wallets.

package/skills/moonpay-buy-crypto/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: moonpay-buy-crypto
+description: Buy crypto with fiat via MoonPay. Returns a checkout URL to complete the purchase in a browser.
+tags: [trading]
+---
+
+# Buy crypto with fiat
+
+## Goal
+
+Generate a MoonPay checkout URL for buying crypto with a credit card or bank transfer. The user completes the purchase in their browser.
+
+## Command
+
+```bash
+mp buy \
+  --token <currency-code> \
+  --amount <amount> \
+  --wallet <destination-address> \
+  --email <buyer-email>
+```
+
+## Supported tokens
+
+`sol`, `usdc_sol`, `eth`, `usdc`, `usdc_base`, `usdc_arbitrum`, `usdc_optimism`, `usdc_polygon`, `eth_polygon`, `eth_optimism`, `eth_base`, `eth_arbitrum`
+
+## Example flow
+
+1. User: "I want to buy 1 SOL with my credit card."
+2. Run: `mp buy --token sol --amount 1 --wallet <address> --email user@example.com`
+3. Return the checkout URL for the user to open in their browser.
+
+## Notes
+
+- This is fiat-to-crypto (credit card / bank), not a token swap.
+- For token-to-token swaps, use the **moonpay-swap-tokens** skill instead.
+- The `--token` flag uses MoonPay currency codes, not mint addresses.
+- The checkout URL handles KYC and payment processing.
+
+## Related skills
+
+- **moonpay-swap-tokens** — Swap between tokens (no fiat).
+- **moonpay-discover-tokens** — Search for tokens.
+- **moonpay-auth** — Ensure user is logged in.

package/skills/moonpay-check-wallet/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: moonpay-check-wallet
+description: Check wallet balances and holdings. Use for "what's in my wallet", portfolio breakdown, token balances, and USD values.
+tags: [portfolio]
+---
+
+# Check wallet
+
+## Goal
+
+List all token balances held in a wallet with current USD values.
+
+## Commands
+
+```bash
+# List balances for a Solana wallet
+mp token balance list --wallet <address> --chain solana
+
+# List balances for an EVM wallet
+mp token balance list --wallet 0x... --chain ethereum
+mp token balance list --wallet 0x... --chain base
+```
+
+## Supported chains
+
+`solana`, `ethereum`, `base`, `polygon`, `arbitrum`, `optimism`
+
+## Output handling
+
+- Summarize top holdings by USD value.
+- Call out small dust balances separately.
+- Sum `balance.value` across items for total portfolio value.
+
+## Example flow
+
+1. User: "What's in my wallet?"
+2. Run `mp wallet list` to find the user's wallet address.
+3. Run `mp token balance list --wallet <address> --chain solana`.
+4. Present holdings sorted by value.
+
+## Related skills
+
+- **moonpay-auth** — Set up wallets if none exist.
+- **moonpay-portfolio-report** — Full report with allocation percentages.
+- **moonpay-rug-check** — Risk-check a token before buying.

package/skills/moonpay-discover-tokens/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: moonpay-discover-tokens
+description: Search for tokens and retrieve detailed market data. Use to find token addresses, check prices, volume, liquidity, and trading activity.
+tags: [research]
+---
+
+# Discover tokens
+
+## Goal
+
+Search for tokens by name/symbol and retrieve detailed market data including price, volume, liquidity, and trading activity.
+
+## Commands
+
+### Search for tokens
+
+```bash
+mp token search --query "SOL" --chain solana
+mp token search --query "BONK" --chain solana --limit 3
+```
+
+Returns matching tokens with market data (price, volume, liquidity, trades, buys/sells, unique wallets).
+
+### Retrieve token details
+
+```bash
+mp token retrieve --token <mint-address> --chain solana
+```
+
+Returns token metadata (name, symbol, decimals, image) and market data.
+
+## Supported chains
+
+`solana`, `ethereum`, `base`, `polygon`, `arbitrum`, `optimism`
+
+## Workflow
+
+1. Search by name/symbol with `mp token search`.
+2. Use the returned address to get details with `mp token retrieve`.
+3. Evaluate risk with **moonpay-rug-check** for unknown tokens.
+4. Proceed to buy/swap if desired.
+
+## Example flow
+
+1. User: "What's the price of BONK?"
+2. Run: `mp token search --query "BONK" --chain solana`
+3. Present: name, symbol, price, 24h change, volume, liquidity.
+
+## Related skills
+
+- **moonpay-token-brief** — Detailed trading brief for a specific token.
+- **moonpay-rug-check** — Risk assessment for unknown tokens.
+- **moonpay-swap-tokens** — Swap after research.
+- **moonpay-buy-crypto** — Buy with fiat after research.

package/skills/moonpay-env/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: moonpay-env
+description: Ensure the MoonPay CLI environment is set up correctly. Use when commands fail due to PATH or config issues.
+tags: [setup]
+---
+
+# MoonPay environment setup
+
+## Install
+
+```bash
+npm i -g @moonpay/cli
+```
+
+This installs the `mp` (and `moonpay`) binary globally.
+
+## Verify installation
+
+```bash
+mp --version
+mp --help
+```
+
+## Config locations
+
+- **Credentials:** `~/.config/moonpay/credentials.json` (OAuth tokens)
+- **Config:** `~/.config/moonpay/config.json` (base URL, client ID)
+- **Wallets:** `~/.config/moonpay/wallets/` (local keypairs, 0600 permissions)
+
+## Environment for scripts/agents
+
+If running `mp` from a script or agent subprocess, ensure PATH includes the npm global bin:
+
+```bash
+export PATH="$(npm config get prefix)/bin:$PATH"
+mp --version
+```
+
+## Output formats
+
+The CLI supports three output formats via `-f`:
+
+```bash
+mp -f json wallet list    # Pretty JSON (default)
+mp -f compact wallet list # Single-line JSON
+mp -f table wallet list   # ASCII table
+```
+
+## Troubleshooting
+
+- **"command not found"** — `npm i -g @moonpay/cli` and check PATH.
+- **401 / auth errors** — Run `mp login`.
+- **"fetch failed"** — Check network connectivity to agents.moonpay.com.
+
+## Related skills
+
+- **moonpay-auth** — Login, logout, wallet management.

package/skills/moonpay-portfolio-report/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: moonpay-portfolio-report
+description: Generate a portfolio summary with holdings, allocation breakdown, and USD totals. Use when the user asks for a portfolio overview or report.
+tags: [portfolio]
+---
+
+# Portfolio report
+
+## Goal
+
+Produce a structured portfolio report for a wallet: holdings with USD values, allocation percentages, and total portfolio value.
+
+## Commands
+
+```bash
+# Get all balances
+mp token balance list --wallet <address> --chain solana
+
+# Get details on a specific token (optional)
+mp token retrieve --token <mint-address> --chain solana
+```
+
+## Workflow
+
+1. Run `mp wallet list` to find the user's wallet address.
+2. Call `mp token balance list` with the wallet and chain.
+3. Sort holdings by USD value descending.
+4. Calculate allocation percentages (each holding's USD / total USD).
+5. Format into sections: Top Holdings, Dust Balances, Total Value.
+
+## Example flow
+
+1. User: "Generate a portfolio report."
+2. Run: `mp token balance list --wallet <address> --chain solana`
+3. Present:
+   - **Total value:** $168.05
+   - **SOL** — 0.61 ($51.87) — 30.9%
+   - **WBTC** — 0.00127 ($85.48) — 50.9%
+   - **USDC** — 29.81 ($29.81) — 17.7%
+   - **Dust:** none
+
+## Output formats
+
+Use `mp -f table token balance list ...` for a quick table view, or `mp -f json ...` for programmatic processing.
+
+## Related skills
+
+- **moonpay-check-wallet** — Quick balance check (this skill builds on it).
+- **moonpay-discover-tokens** — Research specific tokens in the portfolio.

package/skills/moonpay-rug-check/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: moonpay-rug-check
+description: Analyze a token for rug pull risk indicators. Use when the user asks "is this token safe?" or wants to evaluate an unknown token before buying.
+tags: [research]
+---
+
+# Rug check
+
+## Goal
+
+Assess a token's risk profile using available market data. Give the user a clear risk summary before they buy.
+
+## Commands
+
+```bash
+# Resolve token address
+mp token search --query "BONK" --chain solana
+
+# Get market data
+mp token retrieve --token <mint-address> --chain solana
+```
+
+## Risk indicators to check
+
+1. **Liquidity** — Low liquidity = easy to manipulate. Under $10K is a red flag.
+2. **Volume pattern** — Compare 5m/1h/4h/24h volume. Sudden spikes with no context = suspicious.
+3. **Buy/sell ratio** — Heavy sell pressure or extremely one-sided trading = dump risk.
+4. **Unique wallets** — Very few unique wallets trading = concentrated activity.
+5. **Market cap vs liquidity** — Huge mcap with tiny liquidity = inflated, hard to exit.
+6. **Price volatility** — Extreme short-term swings (>50% in 1h) = high risk.
+
+## Workflow
+
+1. Resolve token via `mp token search` if user provides name/symbol.
+2. Call `mp token retrieve` for market data.
+3. Analyze against risk indicators above.
+4. Present a risk summary with traffic-light ratings.
+
+## Example flow
+
+1. User: "Is BONK safe to buy?"
+2. Search: `mp token search --query "BONK" --chain solana`
+3. Retrieve: `mp token retrieve --token <address> --chain solana`
+4. Present:
+   - Liquidity: $12M (green)
+   - Volume 24h: $45M (green)
+   - Buy/sell ratio: balanced (green)
+   - Unique wallets 24h: 3,200 (green)
+   - **Overall: Low risk**
+
+## Notes
+
+- This is a heuristic check based on market data, not a smart contract audit.
+- Always recommend caution with unknown tokens regardless of data.
+
+## Related skills
+
+- **moonpay-discover-tokens** — Token search and research.
+- **moonpay-token-brief** — Detailed market data brief.

package/skills/moonpay-swap-tokens/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: moonpay-swap-tokens
+description: Swap tokens using the build, sign, execute flow. Use when the user wants to swap token A for token B on Solana.
+tags: [trading]
+---
+
+# Swap tokens
+
+## Goal
+
+Swap tokens on Solana using the three-step flow: build an unsigned transaction, sign it locally with a wallet, then execute it on-chain.
+
+## Tools
+
+- `token swap build` — Build an unsigned swap transaction (returns base64 tx + quote)
+- `transaction sign` — Sign the transaction with a local wallet
+- `token swap execute` — Submit the signed transaction to Jupiter
+
+## Workflow
+
+### 1. Build the swap transaction
+
+```bash
+mp token swap build \
+  --input <input-token-mint> \
+  --output <output-token-mint> \
+  --amount <amount-of-input-token> \
+  --wallet <wallet-address>
+```
+
+This returns a `transaction` (base64), `message` (human-readable quote), and `requestId`.
+
+### 2. Sign the transaction locally
+
+```bash
+mp transaction sign \
+  --transaction <base64-transaction> \
+  --wallet <wallet-address>
+```
+
+This returns a signed `transaction` (base64). The private key never leaves the machine.
+
+### 3. Execute the swap
+
+```bash
+mp token swap execute \
+  --transaction <signed-base64-transaction> \
+  --requestId <request-id-from-build>
+```
+
+This returns a `signature` (the on-chain transaction hash).
+
+## Example flow
+
+1. User: "Swap 1 USDC for WBTC"
+2. Resolve token addresses via `mp token search --query "USDC" --chain solana`.
+3. Build: `mp token swap build --input EPjF...Dt1v --output 3NZ9...cmJh --amount 1 --wallet <addr>`
+4. Show the quote from the `message` field. Ask for confirmation.
+5. Sign: `mp transaction sign --transaction <tx> --wallet <addr>`
+6. Execute: `mp token swap execute --transaction <signed-tx> --requestId <id>`
+7. Return the transaction signature.
+
+## Notes
+
+- If the user provides token names/symbols, resolve to addresses with `mp token search`.
+- Always show the quote and ask for confirmation before signing.
+- The wallet must be a local wallet (see `mp wallet list`).
+
+## Related skills
+
+- **moonpay-discover-tokens** — Search for token addresses.
+- **moonpay-check-wallet** — Check balances before swapping.
+- **moonpay-auth** — Set up wallets for signing.

package/skills/moonpay-token-brief/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: moonpay-token-brief
+description: Generate a concise trading brief for a token with market cap, liquidity, volume, momentum, and activity metrics.
+tags: [research]
+---
+
+# Token brief
+
+## Goal
+
+Given a token address, produce a compact brief with key trading metrics.
+
+## Command
+
+```bash
+mp token retrieve --token <mint-address> --chain solana
+```
+
+## What to include
+
+- **Identity:** name, symbol, address
+- **Market data:**
+  - Market cap, liquidity, volume (24h)
+  - Price change % (5m, 1h, 4h, 12h, 24h)
+  - Trades, buys/sells, unique wallets (5m through 24h)
+- **Risk notes:** thin liquidity, cooling volume, extreme swings
+
+## Example output format
+
+```
+BONK (DezX...pump) — mcap $850M, liq $12M, vol24 $45M
+  momentum: 1h +2.3%, 4h -0.5%, 24h +8.1%
+  activity: trades24 12,500, wallets24 3,200
+  note: healthy volume, broad wallet distribution
+```
+
+## Workflow
+
+1. If user provides name/symbol, resolve with `mp token search`.
+2. Call `mp token retrieve` for the full data.
+3. Format into a brief.
+
+## Related skills
+
+- **moonpay-discover-tokens** — Search if you only have a name/symbol.
+- **moonpay-rug-check** — Risk assessment for unknown tokens.
+- **moonpay-swap-tokens** — Trade after analysis.

package/skills/moonpay-virtual-account/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: moonpay-virtual-account
+description: Set up a virtual account for fiat on/off-ramp. Covers KYC, bank accounts, onramp (fiat to stablecoin), offramp (stablecoin to fiat), and wallet registration.
+tags: [defi]
+---
+
+# Virtual account (fiat on/off-ramp)
+
+## Goal
+
+Set up and use a MoonPay virtual account to convert between fiat (USD/EUR) and stablecoins (USDC/USDT/EURC) on Solana. Covers the full lifecycle: account creation, KYC, bank account registration, onramp, and offramp.
+
+## Setup flow
+
+### 1. Create account and start KYC
+
+```bash
+mp virtual-account create
+```
+
+### 2. Check account status
+
+```bash
+mp virtual-account retrieve
+```
+
+The `status` field shows where you are. The `next_step` field tells you what to do next.
+
+### 3. Complete KYC verification
+
+```bash
+# Create a verification link
+mp virtual-account identification create
+
+# Check verification status
+mp virtual-account identification retrieve
+
+# List all verifications
+mp virtual-account identification list
+```
+
+### 4. Sign required documents
+
+```bash
+# List documents needing signature
+mp virtual-account signing required list
+
+# Sign a document
+mp virtual-account signing create --contentId <content-id>
+
+# List signed documents
+mp virtual-account signing list
+```
+
+### 5. Register a wallet
+
+The wallet must be verified via a signed message before it can receive funds.
+
+```bash
+# Create verification message
+mp virtual-account wallet registration-message create --wallet <address>
+
+# Sign the message with your local wallet
+mp message sign --wallet <address> --message "<verification-message>"
+
+# Register the wallet with the signature
+mp virtual-account wallet register \
+  --wallet <address> \
+  --message "<verification-message>" \
+  --signature <base58-signature>
+
+# List registered wallets
+mp virtual-account wallet list
+```
+
+## Onramp (fiat to stablecoin)
+
+```bash
+# Create an onramp
+mp virtual-account onramp create \
+  --name "My Onramp" \
+  --fiat USD \
+  --stablecoin USDC
+
+# Get onramp details (includes bank info for wire/ACH)
+mp virtual-account onramp retrieve --onrampId <id>
+
+# List onramps
+mp virtual-account onramp list --status Created
+
+# Create an open banking payment
+mp virtual-account onramp payment create \
+  --onrampId <id> \
+  --amount 100 \
+  --fiat USD
+
+# Check payment status
+mp virtual-account onramp payment retrieve \
+  --onrampId <id> \
+  --paymentId <payment-id>
+```
+
+## Offramp (stablecoin to fiat)
+
+### Register a bank account first
+
+```bash
+# USD bank account
+mp virtual-account bank-account usd register \
+  --type ACH \
+  --accountNumber <number> \
+  --routingNumber <number> \
+  --address "123 Main St" \
+  --email user@example.com \
+  --phoneNumber "+1..." \
+  --providerCountry US \
+  --providerName "Bank Name" \
+  --givenName "First" \
+  --familyName "Last"
+
+# EUR bank account
+mp virtual-account bank-account eur register \
+  --iban <iban> \
+  --address "123 Main St" \
+  --email user@example.com \
+  --phoneNumber "+1..." \
+  --providerCountry DE \
+  --providerName "Bank Name" \
+  --givenName "First" \
+  --familyName "Last"
+
+# List bank accounts
+mp virtual-account bank-account list
+```
+
+### Create and execute offramp
+
+```bash
+# Create offramp
+mp virtual-account offramp create \
+  --name "My Offramp" \
+  --fiat USD \
+  --stablecoin USDC
+
+# Build the send transaction
+mp virtual-account offramp initiate \
+  --offrampId <id> \
+  --wallet <address> \
+  --amount 100
+
+# Sign and send the transaction
+mp transaction sign --transaction <base64-tx> --wallet <address>
+mp transaction send --transaction <signed-tx> --message "Offramp 100 USDC"
+```
+
+## Other commands
+
+```bash
+# List transactions
+mp virtual-account transaction list
+
+# Delete account
+mp virtual-account delete
+
+# Delete a bank account
+mp virtual-account bank-account delete --bankAccountId <id>
+```
+
+## Related skills
+
+- **moonpay-auth** — Login and wallet setup (required before virtual account).
+- **moonpay-check-wallet** — Check stablecoin balances.
+- **moonpay-swap-tokens** — Swap stablecoins for other tokens after onramp.