@agnic/wallet-skills 1.1.0 → 1.2.0

package/.agents/skills/authenticate-wallet/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: authenticate-wallet
+description: Sign in to AgnicPay wallet via browser-based OAuth
+user-invocable: true
+disable-model-invocation: false
+allowed-tools: ["Bash(npx agnic@latest *)"]
+---
+
+# Authenticate Wallet
+
+Authenticate the user with their AgnicPay wallet using browser-based OAuth login.
+
+## Steps
+
+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.
+
+2. Wait for the browser flow to complete. The CLI will show "Authenticated!" when done.
+
+3. Verify authentication:
+   ```bash
+   npx agnic@latest status --json
+   ```
+
+## Expected Output
+
+```json
+{
+  "authenticated": true,
+  "userId": "did:privy:...",
+  "email": "user@example.com",
+  "walletAddress": "0x...",
+  "tokenExpiry": "2026-05-22T..."
+}
+```
+
+## Error Handling
+
+- 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.
+
+## Logout
+
+To remove stored credentials:
+```bash
+npx agnic@latest auth logout
+```

package/.agents/skills/check-balance/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: check-balance
+description: Check USDC balance across networks (Base, Solana)
+user-invocable: true
+disable-model-invocation: false
+allowed-tools: ["Bash(npx agnic@latest *)"]
+---
+
+# Check Balance
+
+Check the user's USDC balance across supported networks.
+
+## Steps
+
+1. Verify authentication:
+   ```bash
+   npx agnic@latest status --json
+   ```
+   If not authenticated, run `npx agnic@latest auth login` first.
+
+2. Check balance for all networks:
+   ```bash
+   npx agnic@latest balance --json
+   ```
+
+3. Or check a specific network:
+   ```bash
+   npx agnic@latest balance --network base --json
+   npx agnic@latest balance --network solana --json
+   ```
+
+## Expected Output
+
+```json
+[
+  { "network": "base", "balance": "125.50", "address": "0x..." },
+  { "network": "solana", "balance": "0", "address": "N/A" }
+]
+```
+
+## Supported Networks
+
+- `base` — Base mainnet (EVM, primary)
+- `solana` — Solana mainnet
+- `base-sepolia` — Base testnet
+- `solana-devnet` — Solana devnet
+
+## 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

package/.agents/skills/fund-wallet/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: fund-wallet
+description: Get instructions for funding your AgnicPay wallet
+user-invocable: true
+disable-model-invocation: false
+allowed-tools: ["Bash(npx agnic@latest *)"]
+---
+
+# Fund Wallet
+
+Provide instructions for adding funds to the user's AgnicPay wallet.
+
+## Steps
+
+1. Check if the user is authenticated:
+   ```bash
+   npx agnic@latest status --json
+   ```
+
+2. Show the user's wallet address:
+   ```bash
+   npx agnic@latest address --json
+   ```
+
+3. Explain funding options:
+
+   **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
+
+   **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
+
+4. After funding, verify the balance:
+   ```bash
+   npx agnic@latest balance --json
+   ```
+
+## 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

package/.agents/skills/get-agent-identity/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: get-agent-identity
+description: Check your agent's on-chain ERC-8004 identity and trust score
+user-invocable: true
+disable-model-invocation: false
+allowed-tools: ["Bash(npx agnic@latest *)"]
+---
+
+# Get Agent Identity
+
+Check the user's on-chain ERC-8004 agent identity, trust score, and KYA credentials.
+
+## Steps
+
+1. Verify authentication:
+   ```bash
+   npx agnic@latest status --json
+   ```
+
+2. Check agent identity:
+   ```bash
+   npx agnic@latest agent-identity --json
+   ```
+   Note: If `agent-identity` is not available, use the API directly:
+   ```bash
+   npx agnic@latest x402 pay "https://api.agnic.ai/api/agent/identity" --method GET --json
+   ```
+
+## What is ERC-8004?
+
+ERC-8004 ("Trustless Agents") is an Ethereum standard that gives AI agents:
+- **On-chain identity** — An NFT representing the agent
+- **Reputation score** — Trust score based on transaction history
+- **Verifiable credentials** — KYA (Know Your Agent) credentials for identity verification
+
+## Expected Output
+
+```json
+{
+  "agentId": 373,
+  "ownerAddress": "0x046906b3...",
+  "status": "active",
+  "registeredAt": "2024-12-15T...",
+  "trustScore": 85,
+  "categories": ["payment", "general"]
+}
+```
+
+## Error Handling
+
+- If the user doesn't have an agent identity, they can create one via the AgnicPay dashboard
+- Agent identity is automatically created during OAuth sign-up

package/.agents/skills/pay-for-service/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: pay-for-service
+description: Make paid requests to x402-enabled APIs
+user-invocable: true
+disable-model-invocation: false
+allowed-tools: ["Bash(npx agnic@latest *)"]
+---
+
+# Pay for Service
+
+Make a paid x402 request to an API endpoint. AgnicPay handles the payment automatically.
+
+## Steps
+
+1. Verify authentication:
+   ```bash
+   npx agnic@latest status --json
+   ```
+
+2. Check balance to ensure sufficient funds:
+   ```bash
+   npx agnic@latest balance --network base --json
+   ```
+
+3. Make the x402 payment request:
+   ```bash
+   npx agnic@latest x402 pay "<url>" --json
+   ```
+
+4. For POST requests with a body:
+   ```bash
+   npx agnic@latest x402 pay "<url>" --method POST --body '{"key": "value"}' --json
+   ```
+
+## Parameters
+
+- `<url>` — Full URL of the x402-enabled API endpoint
+- `--method` — HTTP method (default: GET)
+- `--body` — Request body as JSON string (for POST/PUT)
+
+## Example
+
+```bash
+npx agnic@latest x402 pay "https://api.example.com/analysis" \
+  --method POST \
+  --body '{"query": "latest market data"}' \
+  --json
+```
+
+## Expected Output
+
+```json
+{
+  "status": 200,
+  "cost": "0.001",
+  "network": "base",
+  "transactionHash": "0xabc123...",
+  "data": { "result": "..." }
+}
+```
+
+## Error Handling
+
+- If not authenticated: prompt user to run `npx agnic@latest auth login`
+- If balance is insufficient, inform the user and suggest funding
+- If the API returns an error, show the status code and response body
+- The `--body` flag must be valid JSON; if invalid, the CLI will report the parse error

package/.agents/skills/search-for-service/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: search-for-service
+description: Search for x402-enabled APIs and services
+user-invocable: true
+disable-model-invocation: false
+allowed-tools: ["Bash(npx agnic@latest *)"]
+---
+
+# Search for Service
+
+Discover x402-enabled APIs that can be paid for using AgnicPay.
+
+## Steps
+
+1. Search for APIs matching the user's query:
+   ```bash
+   npx agnic@latest x402 search "<query>" --json
+   ```
+
+2. Optionally filter by category:
+   ```bash
+   npx agnic@latest x402 search "<query>" --category AI --json
+   ```
+
+3. Present the results to the user with names, descriptions, prices, and URLs.
+
+## Parameters
+
+- `<query>` — Search term (e.g., "sentiment analysis", "weather data")
+- `--category` — Filter by category: AI, Crypto, Data, Trading, Finance, Weather
+- `--limit <n>` — Max results (default: 10)
+
+## Example
+
+```bash
+npx agnic@latest x402 search "sentiment analysis" --category AI --json
+```
+
+## Expected Output
+
+```json
+{
+  "apis": [
+    {
+      "name": "Sentiment Pro",
+      "description": "Real-time sentiment analysis",
+      "price": "0.001",
+      "url": "https://api.example.com/sentiment"
+    }
+  ]
+}
+```
+
+## Error Handling
+
+- If no results found, suggest broadening the search or trying different keywords
+- Authentication is NOT required for search (it's a public endpoint)

package/.agents/skills/send-usdc/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: send-usdc
+description: Send USDC to a wallet address on Base or Solana
+user-invocable: true
+disable-model-invocation: false
+allowed-tools: ["Bash(npx agnic@latest *)"]
+---
+
+# Send USDC
+
+Send USDC from the user's wallet to a recipient address.
+
+## Steps
+
+1. Verify authentication:
+   ```bash
+   npx agnic@latest status --json
+   ```
+
+2. Check balance to ensure sufficient funds:
+   ```bash
+   npx agnic@latest balance --network base --json
+   ```
+
+3. Confirm with the user: the amount, recipient address, and network.
+
+4. Send USDC:
+   ```bash
+   npx agnic@latest send <amount> <recipient_address> --network base --json
+   ```
+
+## Parameters
+
+- `<amount>` — Amount in USDC (e.g., `5.00`)
+- `<recipient_address>` — Destination wallet address (0x... for EVM)
+- `--network` — Network to send on (default: `base`)
+- `--memo` — Optional transaction memo
+
+## Example
+
+```bash
+npx agnic@latest send 5.00 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7 --network base --json
+```
+
+## Expected Output
+
+```json
+{
+  "amount": "5.00",
+  "to": "0x742d35Cc...",
+  "network": "base",
+  "transactionHash": "0xabc123...",
+  "explorerUrl": "https://basescan.org/tx/0xabc123..."
+}
+```
+
+## Error Handling
+
+- If balance is insufficient, inform the user and suggest funding their wallet
+- Always confirm the recipient address and amount before sending
+- If the transaction fails, show the error message from the API

package/.agents/skills/trade-tokens/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: trade-tokens
+description: Trade/swap tokens on Base (USDC, ETH, WETH, cbETH, DAI, AERO)
+user-invocable: true
+disable-model-invocation: false
+allowed-tools: ["Bash(npx agnic@latest *)"]
+---
+
+# Trade Tokens
+
+Swap tokens on Base mainnet using AgnicPay's DEX integration.
+
+## Steps
+
+1. Verify authentication:
+   ```bash
+   npx agnic@latest status --json
+   ```
+
+2. Check balance to ensure sufficient funds:
+   ```bash
+   npx agnic@latest balance --network base --json
+   ```
+
+3. Preview the trade (optional but recommended):
+   ```bash
+   npx agnic@latest trade <amount> <sell_token> <buy_token> --dry-run --json
+   ```
+
+4. Confirm with the user: amount, tokens, and estimated output.
+
+5. Execute the trade:
+   ```bash
+   npx agnic@latest trade <amount> <sell_token> <buy_token> --json
+   ```
+
+## Supported Tokens
+
+USDC, ETH, WETH, cbETH, DAI, AERO (case-insensitive)
+
+## Parameters
+
+- `<amount>` — Amount of the sell token
+- `<sell_token>` — Token to sell (e.g., `usdc`)
+- `<buy_token>` — Token to buy (e.g., `eth`)
+- `--slippage <percent>` — Max slippage (default: `1.0`)
+- `--dry-run` — Show quote without executing
+
+## Example
+
+```bash
+# Preview
+npx agnic@latest trade 10 usdc eth --dry-run --json
+
+# Execute
+npx agnic@latest trade 10 usdc eth --json
+```
+
+## Expected Output
+
+```json
+{
+  "success": true,
+  "sellAmount": "10",
+  "sellToken": "USDC",
+  "buyAmount": "0.00396",
+  "buyToken": "ETH",
+  "price": "2525.25",
+  "transactionHash": "0xabc123...",
+  "explorerUrl": "https://basescan.org/tx/0xabc123..."
+}
+```
+
+## Error Handling
+
+- Always preview with `--dry-run` first to show the user expected output
+- If slippage is too high, suggest a lower amount or higher slippage tolerance
+- Trading is only available on Base mainnet

package/README.md

@@ -1,39 +1,63 @@
-# @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 |
 
 ## 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.0",
   "description": "Vercel AI SDK skills for AgnicPay wallet — balance, payments, trading, x402, and agent identity",
   "keywords": [
     "agnic",

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