@agnic/wallet-skills 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,39 @@
+# @agnic/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.
+
+## Installation
+
+```bash
+npx skills add @agnic/wallet-skills
+```
+
+## Prerequisites
+
+The agent must be authenticated with the `agnic` CLI:
+
+```bash
+npx agnic@latest auth login
+# Opens browser → sign in → set spending limits → done
+```
+
+## Available Skills
+
+| 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 |
+
+## How It Works
+
+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.
+
+## Documentation
+
+Full docs at [docs.agnic.ai/docs/agnicpay-features/skills](https://docs.agnic.ai/docs/agnicpay-features/skills)

package/package.json

@@ -1,24 +1,20 @@
 {
   "name": "@agnic/wallet-skills",
-  "version": "1.0.0",
-  "description": "AI agent wallet skills for x402 payments, token trading, and identity",
-  "skills": "skills/",
-  "files": [
-    "skills/"
-  ],
+  "version": "1.1.0",
+  "description": "Vercel AI SDK skills for AgnicPay wallet — balance, payments, trading, x402, and agent identity",
   "keywords": [
-    "vercel-ai-skills",
+    "agnic",
+    "agnicpay",
+    "skills",
+    "vercel-ai",
     "x402",
     "wallet",
-    "ai-agent",
-    "trading",
-    "erc-8004",
-    "agnicpay"
+    "ai-agent"
   ],
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/agnicpay/agnic-wallet-skills"
+    "url": "https://github.com/agnic-protocol/agnic-wallet-skills"
   },
   "homepage": "https://docs.agnic.ai/docs/agnicpay-features/skills"
 }

package/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/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/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/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/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/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/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/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/skills/authenticate-wallet.md

@@ -1,18 +0,0 @@
----
-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.md

@@ -1,15 +0,0 @@
----
-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.md

@@ -1,17 +0,0 @@
----
-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

package/skills/get-agent-identity.md

@@ -1,19 +0,0 @@
----
-name: get-agent-identity
-description: Check agent's on-chain identity, trust score, and KYA credentials. Use when the user asks about agent identity, trust, reputation, or credentials.
----
-
-## Instructions
-
-1. Check auth status: `npx agnic status --json`
-2. If authenticated, show the agent's wallet address and identity info
-3. Explain what ERC-8004 agent identity provides:
-   - On-chain identity (NFT-based)
-   - Trust score and reputation
-   - KYA (Know Your Agent) credentials for identity verification
-   - Delegation credentials for authorized actions
-4. Direct user to https://pay.agnic.ai for full identity management
-
-## Allowed Tools
-- npx agnic status
-- npx agnic address

package/skills/pay-for-service.md

@@ -1,16 +0,0 @@
----
-name: pay-for-service
-description: Make a paid request to an x402-enabled API. Use when the user wants to call, use, or pay for an API service.
----
-
-## Instructions
-
-1. Confirm the API URL and HTTP method with the user
-2. Check balance: `npx agnic balance --network base --json`
-3. Execute: `npx agnic x402 pay <url> --method <METHOD> --json`
-4. If the request needs a body, add `--body '{"key":"value"}'`
-5. Present the API response and cost to the user
-
-## Allowed Tools
-- npx agnic balance
-- npx agnic x402 pay

package/skills/search-for-service.md

@@ -1,15 +0,0 @@
----
-name: search-for-service
-description: Search for x402-enabled APIs and services. Use when the user wants to find, discover, or browse available paid APIs.
----
-
-## Instructions
-
-1. Run `npx agnic x402 search "<query>" --json` with the user's search terms
-2. Present results with name, description, and price per request
-3. If user wants to filter by category, add `--category <category>`
-
-Available categories: AI, Crypto, Data, Trading, Finance, Weather
-
-## Allowed Tools
-- npx agnic x402 search

package/skills/send-usdc.md

@@ -1,19 +0,0 @@
----
-name: send-usdc
-description: Send USDC to a wallet address. Use when the user wants to send, transfer, or pay someone USDC.
----
-
-## Instructions
-
-1. Confirm the recipient address and amount with the user
-2. Check balance first: `npx agnic balance --network base --json`
-3. If sufficient funds, execute: `npx agnic send <amount> <address> --json`
-4. Report the transaction hash and explorer link
-
-Optional flags:
-- `--network <network>` — default is "base"
-- `--memo <text>` — attach a memo to the transaction
-
-## Allowed Tools
-- npx agnic balance
-- npx agnic send

package/skills/trade-tokens.md

@@ -1,22 +0,0 @@
----
-name: trade-tokens
-description: Trade/swap tokens on Base. Use when the user wants to buy, sell, swap, trade, or exchange tokens like ETH, USDC, DAI, AERO, cbETH.
----
-
-## Instructions
-
-1. Confirm which tokens to trade and the amount
-2. Check balance: `npx agnic balance --network base --json`
-3. Optionally preview: `npx agnic trade <amount> <sellToken> <buyToken> --dry-run --json`
-4. Execute trade: `npx agnic trade <amount> <sellToken> <buyToken> --json`
-5. Report results: tokens received, price, transaction hash
-
-Supported tokens: USDC, ETH, WETH, cbETH, DAI, AERO
-
-Optional flags:
-- `--slippage <percent>` — max slippage percentage (default: 1.0)
-- `--dry-run` — show quote without executing
-
-## Allowed Tools
-- npx agnic balance
-- npx agnic trade