@agnic/wallet-skills 1.1.0 → 1.2.1

package/README.md

@@ -1,39 +1,65 @@
-# @agnic/wallet-skills
+# AgnicPay Agentic Wallet Skills
 
-Pre-built [Vercel AI SDK](https://sdk.vercel.ai/) skills for the [AgnicPay](https://pay.agnic.ai) wallet. Give any AI assistant the ability to check balances, send payments, trade tokens, and call x402-enabled APIs.
+Agent Skills for crypto wallet operations. These skills enable AI agents to authenticate, check balances, send USDC, trade tokens, make x402 payments, and verify on-chain identity using the `agnic` CLI.
+
+## Available Skills
+
+| Skill | Description |
+|-------|-------------|
+| **authenticate-wallet** | Sign in to the wallet via browser OAuth |
+| **check-balance** | Check USDC balance across networks (Base, Solana) |
+| **send-usdc** | Send USDC to Ethereum wallet addresses |
+| **trade-tokens** | Swap/trade tokens on Base (USDC, ETH, WETH, cbETH, DAI, AERO) |
+| **search-for-service** | Search for paid API services via x402 |
+| **pay-for-service** | Make paid API requests via x402 |
+| **fund-wallet** | Get instructions for adding funds to the wallet |
+| **get-agent-identity** | Check on-chain ERC-8004 identity and trust score |
+| **agent-email** | Manage agent email — send, receive, check inbox |
+| **agnic** | Unified skill — all wallet, payment, email, and identity capabilities |
 
 ## Installation
 
+Install with Vercel's [Skills CLI](https://github.com/vercel/skills):
+
 ```bash
-npx skills add @agnic/wallet-skills
+npx skills add agnicpay/agnic-wallet-skills
 ```
 
-## Prerequisites
+## Usage
 
-The agent must be authenticated with the `agnic` CLI:
+Skills are automatically available once installed. The agent will use them when relevant tasks are detected.
 
-```bash
-npx agnic@latest auth login
-# Opens browser → sign in → set spending limits → done
-```
+Examples:
 
-## Available Skills
+- `Sign in to my wallet`
+- `Check my balance`
+- `Send 10 USDC to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7`
+- `Swap 5 USDC for ETH`
+- `Find a sentiment analysis API`
+- `Pay for https://api.example.com/data`
+- `What's my agent identity?`
 
-| Skill | Description |
-|-------|-------------|
-| **authenticate-wallet** | Browser-based OAuth login |
-| **check-balance** | USDC balance across networks |
-| **send-usdc** | Send USDC to a wallet address |
-| **trade-tokens** | Swap tokens on Base (USDC, ETH, etc.) |
-| **search-for-service** | Discover x402-enabled APIs |
-| **pay-for-service** | Make x402 payment requests |
-| **fund-wallet** | Instructions for funding your wallet |
-| **get-agent-identity** | ERC-8004 on-chain identity and trust score |
+## Contributing
+
+To add a new skill:
 
-## How It Works
+1. Create a folder in `./skills/` with a lowercase, hyphenated name
+2. Add a `SKILL.md` file with YAML frontmatter and instructions
+3. See the [Agent Skills specification](https://github.com/vercel/skills) for the complete format
 
-Each skill is a markdown file (`SKILL.md`) that instructs the AI assistant on how to use the `agnic` CLI. When a user's request matches a skill, the AI follows the instructions to execute the right commands.
+### Updating the agnic version
+
+All skills pin `agnic@latest` via `npx agnic@latest`. When testing against a specific version:
+
+```bash
+# Install a specific version
+npm install -g agnic@2.0.0
+```
 
 ## Documentation
 
 Full docs at [docs.agnic.ai/docs/agnicpay-features/skills](https://docs.agnic.ai/docs/agnicpay-features/skills)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agnic/wallet-skills",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Vercel AI SDK skills for AgnicPay wallet — balance, payments, trading, x402, and agent identity",
   "keywords": [
     "agnic",

package/skills/agent-email.md

@@ -0,0 +1,21 @@
+---
+name: agent-email
+description: Manage your agent's email address. Use when the user asks about agent email, sending email, checking inbox, or email setup.
+---
+
+## Instructions
+
+1. Check if agent has an email: `npx agnic@latest email address --json`
+2. If no email exists, create one: `npx agnic@latest email setup --json`
+3. For inbox: `npx agnic@latest email inbox --limit 20 --json`
+4. To send: `npx agnic@latest email send --to <address> --subject "<subject>" --body "<body>"`
+5. To reply: `npx agnic@latest email reply --message-id <id> --body "<reply>"`
+
+Each agent gets a unique address like `agent-123@agnic.ai`. Emails are stored with 30-day retention.
+
+## Allowed Tools
+- npx agnic@latest email address
+- npx agnic@latest email setup
+- npx agnic@latest email inbox
+- npx agnic@latest email send
+- npx agnic@latest email reply

package/skills/agnic/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: agnic
+description: >
+  Complete AI agent wallet with payments, trading, email, and on-chain identity.
+  Use when the user wants to manage their agent's wallet, make payments, trade tokens,
+  send/receive email, or check their agent identity.
+user-invocable: true
+disable-model-invocation: false
+allowed-tools: ["Bash(npx agnic@latest *)"]
+---
+
+## Agnic — Unified Agent Wallet Skill
+
+This skill gives your AI agent a full identity stack: wallet, email, payments, trading, and on-chain identity.
+
+### Authentication
+
+```bash
+npx agnic@latest auth login    # Opens browser for OAuth login
+npx agnic@latest auth logout   # Clear stored credentials
+```
+
+### Balance & Funding
+
+```bash
+npx agnic@latest balance --json                     # All networks
+npx agnic@latest balance --network base --json      # Specific network
+npx agnic@latest address                            # Show wallet address
+```
+
+Supported networks: `base`, `solana`, `base-sepolia`, `solana-devnet`
+
+### X402 Payments
+
+```bash
+# Search for APIs
+npx agnic@latest x402 search "weather data" --json
+
+# Preview cost before paying
+npx agnic@latest x402 preview <url>
+
+# Make a paid API call
+npx agnic@latest x402 pay <url> --method GET --json
+```
+
+### Token Trading
+
+```bash
+# Get a quote
+npx agnic@latest trade quote 10 USDC ETH --json
+
+# Execute a trade (Base mainnet only)
+npx agnic@latest trade 10 USDC ETH --json
+```
+
+Supported tokens: USDC, ETH, WETH, cbETH, DAI, AERO
+
+### Send USDC
+
+```bash
+npx agnic@latest send <amount> <address> --network base --json
+```
+
+### Agent Identity
+
+```bash
+npx agnic@latest agent-identity --json    # ERC-8004 identity, trust score, delegation
+npx agnic@latest status --json            # General account status
+```
+
+### Agent Email
+
+```bash
+npx agnic@latest email address --json                     # Show email alias
+npx agnic@latest email setup --display-name "My Agent"    # Create email alias
+npx agnic@latest email inbox --limit 10 --json            # Check inbox
+npx agnic@latest email send --to user@example.com --subject "Hello" --body "Message"
+npx agnic@latest email reply --message-id <id> --body "Reply text"
+```
+
+### Workflow: Sign Up + Pay + Report
+
+1. Check auth: `npx agnic@latest status --json`
+2. Sign up for a service using agent email (`email send`)
+3. Check inbox for verification (`email inbox`)
+4. Reply to verify (`email reply`)
+5. Make paid API call (`x402 pay`)
+6. Email results to user (`email send`)

package/skills/authenticate-wallet/SKILL.md

@@ -1,51 +1,74 @@
 ---
 name: authenticate-wallet
-description: Sign in to AgnicPay wallet via browser-based OAuth
+description: Sign in to AgnicPay wallet via browser-based OAuth. Use when you or the user want to authenticate, sign in, log in, connect wallet, or set up the CLI. Covers phrases like "sign in", "log in", "authenticate", "connect my wallet", "set up agnic".
 user-invocable: true
 disable-model-invocation: false
-allowed-tools: ["Bash(npx agnic@latest *)"]
+allowed-tools: ["Bash(npx agnic@latest status*)", "Bash(npx agnic@latest auth *)"]
 ---
 
-# Authenticate Wallet
+# Authenticating the AgnicPay Wallet
 
-Authenticate the user with their AgnicPay wallet using browser-based OAuth login.
+Use `npx agnic@latest auth login` to authenticate via browser-based OAuth. This opens the user's default browser to AgnicPay where they sign in and set spending limits for the CLI session.
 
-## Steps
+## Confirm wallet is initialized and authed
 
-1. Run the login command:
-   ```bash
-   npx agnic@latest auth login
-   ```
-   This opens the user's browser to AgnicPay where they sign in and set spending limits.
+```bash
+npx agnic@latest status
+```
+
+If already authenticated, no further action is needed. If not authenticated, proceed with login.
+
+## Login Flow
+
+```bash
+npx agnic@latest auth login
+```
+
+This command:
+1. Starts a temporary local server on a random port
+2. Opens the user's default browser to AgnicPay's OAuth consent screen
+3. The user signs in (email, Google, or wallet) and approves spending limits
+4. The browser redirects back to `http://localhost:<port>/callback`
+5. The CLI exchanges the authorization code for tokens and saves them locally
 
-2. Wait for the browser flow to complete. The CLI will show "Authenticated!" when done.
+Wait for the CLI to print `✓ Authenticated!` before proceeding.
 
-3. Verify authentication:
-   ```bash
-   npx agnic@latest status --json
-   ```
+## Verify Authentication
 
-## Expected Output
+After login, confirm the session is active:
 
-```json
-{
-  "authenticated": true,
-  "userId": "did:privy:...",
-  "email": "user@example.com",
-  "walletAddress": "0x...",
-  "tokenExpiry": "2026-05-22T..."
-}
+```bash
+npx agnic@latest status
 ```
 
-## Error Handling
+Expected output:
 
-- If the user cancels the browser flow, the CLI will show "Authentication failed".
-- If the browser doesn't open, the CLI prints a URL the user can copy manually.
-- If already authenticated, `agnic status` will confirm without re-login.
+```
+Wallet Status
+✓ Authenticated
+
+Email:    user@example.com
+Wallet:   0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7
+Expires:  2026-05-22 14:30:00 UTC
+```
 
 ## Logout
 
 To remove stored credentials:
+
 ```bash
 npx agnic@latest auth logout
 ```
+
+## Token Storage
+
+Credentials are stored in `~/.agnic/config.json` with restricted permissions (`0600`). Tokens auto-refresh on 401 responses — no manual re-authentication needed until the refresh token expires (90 days).
+
+## Error Handling
+
+Common errors:
+
+- "Not authenticated" — Run `npx agnic@latest auth login`
+- "Authentication failed" — User cancelled the browser flow or the timeout (5 min) expired
+- "Could not open browser" — The CLI prints a URL to copy and open manually
+- "Token expired" — Tokens auto-refresh; if refresh also fails, re-run `npx agnic@latest auth login`

package/skills/authenticate-wallet.md

@@ -0,0 +1,18 @@
+---
+name: authenticate-wallet
+description: Sign in to AgnicPay wallet. Use when the user wants to log in, authenticate, or when any command fails with auth errors.
+---
+
+## Instructions
+
+1. Run `npx agnic status` to check current auth state
+2. If not authenticated, ask user for their email
+3. Run `npx agnic auth login <email>` — sends OTP code to their email
+4. Ask user for the 6-digit code from their email
+5. Run `npx agnic auth verify <flowId> <otp>`
+6. Confirm with `npx agnic status`
+
+## Allowed Tools
+- npx agnic status
+- npx agnic auth login
+- npx agnic auth verify

package/skills/check-balance/SKILL.md

@@ -1,51 +1,75 @@
 ---
 name: check-balance
-description: Check USDC balance across networks (Base, Solana)
+description: Check USDC balance across networks. Use when you or the user want to check balance, see how much money is in the wallet, view funds, or check available USDC. Covers phrases like "check my balance", "how much USDC do I have", "what's my balance", "show funds", "wallet balance".
 user-invocable: true
 disable-model-invocation: false
-allowed-tools: ["Bash(npx agnic@latest *)"]
+allowed-tools: ["Bash(npx agnic@latest status*)", "Bash(npx agnic@latest balance*)"]
 ---
 
-# Check Balance
+# Checking USDC Balance
 
-Check the user's USDC balance across supported networks.
+Use the `npx agnic@latest balance` command to check USDC balance across supported networks.
 
-## Steps
+## Confirm wallet is initialized and authed
 
-1. Verify authentication:
-   ```bash
-   npx agnic@latest status --json
-   ```
-   If not authenticated, run `npx agnic@latest auth login` first.
+```bash
+npx agnic@latest status
+```
+
+If the wallet is not authenticated, refer to the `authenticate-wallet` skill.
+
+## Command Syntax
+
+```bash
+npx agnic@latest balance [--network <network>] [--json]
+```
+
+## Options
+
+| Option               | Description                                |
+| -------------------- | ------------------------------------------ |
+| `--network <name>`   | Filter by network (default: all networks)  |
+| `--json`             | Output result as JSON                      |
+
+## Supported Networks
+
+| Network        | Description           |
+| -------------- | --------------------- |
+| `base`         | Base mainnet (primary) |
+| `base-sepolia` | Base testnet          |
+| `solana`       | Solana mainnet        |
+| `solana-devnet`| Solana devnet         |
+
+## Examples
+
+```bash
+# Check balance on all networks
+npx agnic@latest balance
 
-2. Check balance for all networks:
-   ```bash
-   npx agnic@latest balance --json
-   ```
+# Check balance on Base mainnet only
+npx agnic@latest balance --network base
 
-3. Or check a specific network:
-   ```bash
-   npx agnic@latest balance --network base --json
-   npx agnic@latest balance --network solana --json
-   ```
+# Get JSON output
+npx agnic@latest balance --json
+```
 
 ## Expected Output
 
-```json
-[
-  { "network": "base", "balance": "125.50", "address": "0x..." },
-  { "network": "solana", "balance": "0", "address": "N/A" }
-]
+```
+Network       Balance      Address
+base          125.50 USDC  0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7
+base-sepolia    0.00 USDC  0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7
+solana          0.00 USDC  N/A
+solana-devnet   0.00 USDC  N/A
 ```
 
-## Supported Networks
+## Prerequisites
 
-- `base` — Base mainnet (EVM, primary)
-- `solana` — Solana mainnet
-- `base-sepolia` — Base testnet
-- `solana-devnet` — Solana devnet
+- Must be authenticated (`npx agnic@latest status` to check)
 
 ## Error Handling
 
-- If not authenticated: prompt user to run `npx agnic@latest auth login`
-- If a network returns an error, report it and show available balances
+Common errors:
+
+- "Not authenticated" — Run `npx agnic@latest auth login` first
+- Network timeout — Try again or specify a single network with `--network base`

package/skills/check-balance.md

@@ -0,0 +1,15 @@
+---
+name: check-balance
+description: Check USDC balance across networks. Use when the user asks about their balance, funds, or how much they have.
+---
+
+## Instructions
+
+1. Run `npx agnic balance --json` to get balances across all networks
+2. If user asks about a specific network, use `npx agnic balance --network <network> --json`
+3. Present the balance in a clear format with network and amount
+
+Supported networks: base, solana, base-sepolia, solana-devnet
+
+## Allowed Tools
+- npx agnic balance

package/skills/fund-wallet/SKILL.md

@@ -1,46 +1,79 @@
 ---
 name: fund-wallet
-description: Get instructions for funding your AgnicPay wallet
+description: Get instructions for funding your AgnicPay wallet with USDC. Use when you or the user want to add funds, deposit USDC, top up the wallet, or need more balance. Covers phrases like "add funds", "deposit", "top up", "fund my wallet", "how do I get USDC", "need more balance".
 user-invocable: true
 disable-model-invocation: false
-allowed-tools: ["Bash(npx agnic@latest *)"]
+allowed-tools: ["Bash(npx agnic@latest status*)", "Bash(npx agnic@latest address*)", "Bash(npx agnic@latest balance*)"]
 ---
 
-# Fund Wallet
+# Funding the AgnicPay Wallet
 
-Provide instructions for adding funds to the user's AgnicPay wallet.
+Provide instructions for adding USDC to the user's AgnicPay wallet on Base.
 
-## Steps
+## Confirm wallet is initialized and authed
 
-1. Check if the user is authenticated:
-   ```bash
-   npx agnic@latest status --json
-   ```
+```bash
+npx agnic@latest status
+```
 
-2. Show the user's wallet address:
-   ```bash
-   npx agnic@latest address --json
-   ```
+If the wallet is not authenticated, refer to the `authenticate-wallet` skill.
 
-3. Explain funding options:
+## Get Wallet Address
 
-   **Option 1: AgnicPay Dashboard**
-   - Go to [pay.agnic.ai](https://pay.agnic.ai)
-   - Navigate to your dashboard
-   - Use the "Add Funds" feature to deposit USDC
+```bash
+npx agnic@latest address
+```
 
-   **Option 2: Direct Transfer**
-   - Send USDC to your wallet address on Base network
-   - The address is shown by `agnic address`
-   - Use any wallet (MetaMask, Coinbase, etc.) to send USDC on Base
+This displays the user's wallet address on each supported network.
 
-4. After funding, verify the balance:
-   ```bash
-   npx agnic@latest balance --json
-   ```
+## Funding Options
+
+### Option 1: AgnicPay Dashboard (Recommended)
+
+1. Go to [pay.agnic.ai](https://pay.agnic.ai)
+2. Sign in with the same account used in the CLI
+3. Navigate to the dashboard
+4. Use the **"Add Funds"** button to deposit USDC via card, bank transfer, or crypto
+
+### Option 2: Direct USDC Transfer
+
+Send USDC directly to the wallet address on **Base network**:
+
+1. Get the address: `npx agnic@latest address`
+2. From any wallet (MetaMask, Coinbase, Phantom, etc.), send USDC on **Base** to that address
+3. Verify arrival: `npx agnic@latest balance --network base`
+
+**Important**: Send USDC on **Base network** only. USDC on other chains (Ethereum mainnet, Arbitrum, etc.) will not appear in the AgnicPay balance.
+
+### Option 3: Bridge from Another Chain
+
+If the user has USDC on Ethereum, Arbitrum, or Optimism, they can bridge to Base using:
+- [bridge.base.org](https://bridge.base.org) (official Base bridge)
+- Any cross-chain bridge that supports Base
+
+## Verify Balance
+
+After funding, confirm the deposit arrived:
+
+```bash
+npx agnic@latest balance --network base
+```
 
 ## Important Notes
 
-- AgnicPay wallets use USDC (not ETH) for payments and trading
-- Base network is the primary chain
-- Minimum recommended balance: $1.00 USDC for testing
+- AgnicPay wallets use **USDC** (not ETH) for payments and trading
+- **Base network** is the primary chain
+- Minimum recommended balance: **$1.00 USDC** for testing
+- Small amounts of ETH on Base may be needed for gas (auto-handled in most cases)
+
+## Prerequisites
+
+- Must be authenticated (`npx agnic@latest status` to check)
+
+## Error Handling
+
+Common errors:
+
+- "Not authenticated" — Run `npx agnic@latest auth login` first
+- Balance shows 0 after transfer — Verify the transfer was on Base network (not Ethereum mainnet)
+- Transfer pending — Base transactions typically confirm in 2-3 seconds

package/skills/fund-wallet.md

@@ -0,0 +1,17 @@
+---
+name: fund-wallet
+description: Get instructions for funding your AgnicPay wallet. Use when the user needs to add funds, deposit, or top up.
+---
+
+## Instructions
+
+1. Check current balance: `npx agnic balance --json`
+2. Show the wallet address: `npx agnic address`
+3. Provide funding instructions:
+   - Visit https://pay.agnic.ai to fund via the dashboard
+   - Or send USDC directly to the displayed wallet address on Base or Solana
+4. After funding, verify with `npx agnic balance --json`
+
+## Allowed Tools
+- npx agnic balance
+- npx agnic address