@agnic/wallet-skills 1.1.0 → 1.2.0

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

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

@@ -1,52 +1,79 @@
 ---
 name: get-agent-identity
-description: Check your agent's on-chain ERC-8004 identity and trust score
+description: Check your agent's on-chain ERC-8004 identity, trust score, and KYA credentials. Use when you or the user want to see agent identity, check trust score, view KYA credentials, or check agent status. Covers phrases like "what's my agent ID", "check trust score", "show my identity", "agent status", "KYA credentials".
 user-invocable: true
 disable-model-invocation: false
-allowed-tools: ["Bash(npx agnic@latest *)"]
+allowed-tools: ["Bash(npx agnic@latest status*)", "Bash(npx agnic@latest agent-identity*)"]
 ---
 
-# Get Agent Identity
+# Getting Agent Identity
 
-Check the user's on-chain ERC-8004 agent identity, trust score, and KYA credentials.
+Check the user's on-chain ERC-8004 agent identity, trust score, and KYA (Know Your Agent) credentials.
 
-## Steps
+## Confirm wallet is initialized and authed
 
-1. Verify authentication:
-   ```bash
-   npx agnic@latest status --json
-   ```
+```bash
+npx agnic@latest status
+```
+
+If the wallet is not authenticated, refer to the `authenticate-wallet` skill.
+
+## Check Agent Identity
 
-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
-   ```
+```bash
+npx agnic@latest agent-identity --json
+```
+
+This returns the agent's on-chain identity including:
+- **Agent ID** — The ERC-721 token ID on the ERC-8004 Identity Registry
+- **Owner address** — The wallet that owns the agent NFT
+- **Trust score** — Reputation score (0-100) based on transaction history
+- **Categories** — Authorized action categories (e.g., payment, general, alcohol)
+- **Status** — Whether the agent is active or suspended
 
 ## 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
+
+| Feature | Description |
+| ------- | ----------- |
+| **On-chain identity** | An ERC-721 NFT representing the agent on the Identity Registry |
+| **Reputation score** | Trust score (0-100) based on on-chain transaction history |
+| **KYA credentials** | SD-JWT verifiable credentials for identity verification |
+| **Delegation** | Spending limits and category permissions via KYA delegation credentials |
+
+## Contract Addresses
+
+| Contract | Network | Address |
+| -------- | ------- | ------- |
+| Identity Registry | Base Mainnet | `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432` |
+| Identity Registry | Base Sepolia | `0x8004A818BFB912233c491871b3d84c89A494BD9e` |
+| Reputation | Base Mainnet | `0x8004BAa17C55a88189AE136b182e5fdA19dE9b63` |
+| Reputation | Base Sepolia | `0x8004B663056A597Dffe9eCcC1965A193B7388713` |
 
 ## Expected Output
 
 ```json
 {
   "agentId": 373,
-  "ownerAddress": "0x046906b3...",
+  "ownerAddress": "0x046906b3cd9d73bf85eb01d795d333b364b75842",
   "status": "active",
-  "registeredAt": "2024-12-15T...",
+  "registeredAt": "2024-12-15T10:30:00Z",
   "trustScore": 85,
-  "categories": ["payment", "general"]
+  "categories": ["payment", "general"],
+  "hasDelegation": true
 }
 ```
 
+## Prerequisites
+
+- Must be authenticated (`npx agnic@latest status` to check)
+- Agent identity is automatically created during AgnicPay sign-up
+
 ## 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
+Common errors:
+
+- "Not authenticated" — Run `npx agnic@latest auth login` first
+- "No agent identity found" — The user may not have an agent registered yet; create one via the AgnicPay dashboard at [pay.agnic.ai](https://pay.agnic.ai)
+- "Agent suspended" — The agent's delegation may have been revoked; contact support

package/skills/get-agent-identity.md

@@ -0,0 +1,19 @@
+---
+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/SKILL.md

@@ -1,67 +1,109 @@
 ---
 name: pay-for-service
-description: Make paid requests to x402-enabled APIs
+description: Make paid requests to x402-enabled APIs using USDC. Use when you or the user want to call a paid API, make an x402 payment, use a bazaar service, or pay for an API request. Covers phrases like "call this API", "use this service", "pay for the request", "make a paid call", "fetch from x402 endpoint".
 user-invocable: true
 disable-model-invocation: false
-allowed-tools: ["Bash(npx agnic@latest *)"]
+allowed-tools: ["Bash(npx agnic@latest status*)", "Bash(npx agnic@latest x402 pay *)", "Bash(npx agnic@latest x402 details *)", "Bash(npx agnic@latest balance*)"]
 ---
 
-# Pay for Service
+# Paying for x402 Services
 
-Make a paid x402 request to an API endpoint. AgnicPay handles the payment automatically.
+Use the `npx agnic@latest x402 pay` command to call x402-enabled API endpoints with automatic USDC payment on Base.
 
-## Steps
+## Confirm wallet is initialized and authed
 
-1. Verify authentication:
-   ```bash
-   npx agnic@latest status --json
-   ```
+```bash
+npx agnic@latest status
+```
+
+If the wallet is not authenticated, refer to the `authenticate-wallet` skill.
+
+## Command Syntax
+
+```bash
+npx agnic@latest x402 pay <url> [-X <method>] [-d <json>] [-q <params>] [-h <json>] [--max-amount <n>] [--json]
+```
+
+## Arguments & Options
+
+| Option                  | Description                                        |
+| ----------------------- | -------------------------------------------------- |
+| `<url>`                 | Full URL of the x402-enabled API endpoint          |
+| `-X, --method <method>` | HTTP method (default: GET)                         |
+| `-d, --data <json>`     | Request body as JSON string                        |
+| `-q, --query <params>`  | Query parameters as JSON string                    |
+| `-h, --headers <json>`  | Custom HTTP headers as JSON string                 |
+| `--max-amount <amount>` | Max payment in USDC atomic units (1000000 = $1.00) |
+| `--correlation-id <id>` | Group related operations                           |
+| `--json`                | Output as JSON                                     |
+
+## USDC Amounts
 
-2. Check balance to ensure sufficient funds:
+X402 uses USDC atomic units (6 decimals):
+
+| Atomic Units | USD   |
+| ------------ | ----- |
+| 1000000      | $1.00 |
+| 100000       | $0.10 |
+| 50000        | $0.05 |
+| 10000        | $0.01 |
+
+## Input Validation
+
+Before constructing the command, validate:
+
+- **url**: Must be a valid HTTPS URL (`^https://[^\s;|&]+$`). Reject URLs containing spaces, semicolons, pipes, or backticks.
+- **method**: Must be one of GET, POST, PUT, DELETE, PATCH (case-insensitive).
+- **data**: Must be valid JSON. Parse it first; reject if parsing fails.
+- **max-amount**: Must be a positive integer (`^\d+$`).
+
+Do not pass unvalidated user input into the command.
+
+## Workflow
+
+1. **Check requirements first** (optional but recommended):
    ```bash
-   npx agnic@latest balance --network base --json
+   npx agnic@latest x402 details <url>
    ```
+   This shows the price, method, and schema without making a payment.
 
-3. Make the x402 payment request:
+2. **Verify balance**:
    ```bash
-   npx agnic@latest x402 pay "<url>" --json
+   npx agnic@latest balance --network base
    ```
 
-4. For POST requests with a body:
+3. **Make the paid request**:
    ```bash
-   npx agnic@latest x402 pay "<url>" --method POST --body '{"key": "value"}' --json
+   npx agnic@latest x402 pay <url> --json
    ```
 
-## Parameters
+## Examples
 
-- `<url>` — Full URL of the x402-enabled API endpoint
-- `--method` — HTTP method (default: GET)
-- `--body` — Request body as JSON string (for POST/PUT)
+```bash
+# Make a GET request (auto-pays)
+npx agnic@latest x402 pay https://example.com/api/weather
 
-## Example
+# Make a POST request with body
+npx agnic@latest x402 pay https://example.com/api/sentiment -X POST -d '{"text": "I love this product"}'
 
-```bash
-npx agnic@latest x402 pay "https://api.example.com/analysis" \
-  --method POST \
-  --body '{"query": "latest market data"}' \
-  --json
+# Limit max payment to $0.10
+npx agnic@latest x402 pay https://example.com/api/data --max-amount 100000
+
+# Get JSON output
+npx agnic@latest x402 pay https://example.com/api/weather --json
 ```
 
-## Expected Output
+## Prerequisites
 
-```json
-{
-  "status": 200,
-  "cost": "0.001",
-  "network": "base",
-  "transactionHash": "0xabc123...",
-  "data": { "result": "..." }
-}
-```
+- Must be authenticated (`npx agnic@latest auth login`)
+- Wallet must have sufficient USDC balance on Base
 
 ## 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
+Common errors:
+
+- "Not authenticated" — Run `npx agnic@latest auth login` first
+- "Insufficient balance" — Fund wallet with USDC (`npx agnic@latest balance` to check)
+- "No X402 payment requirements found" — URL may not be an x402 endpoint
+- Invalid JSON in `--data` — Ensure the body is valid JSON before passing
+- HTTP 4xx/5xx from the API — Show the status code and response body to the user

package/skills/pay-for-service.md

@@ -0,0 +1,16 @@
+---
+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/SKILL.md

@@ -1,57 +1,85 @@
 ---
 name: search-for-service
-description: Search for x402-enabled APIs and services
+description: Search and browse the x402 bazaar marketplace for paid API services. Use when you or the user want to find available services, see what's available, discover APIs, or need an external service to accomplish a task. Also use as a fallback when no other skill clearly matches — search the bazaar to see if a paid service exists. Covers "what can I do?", "find me an API for...", "what services are available?", "search for...", "browse the bazaar".
 user-invocable: true
 disable-model-invocation: false
-allowed-tools: ["Bash(npx agnic@latest *)"]
+allowed-tools: ["Bash(npx agnic@latest x402 bazaar *)", "Bash(npx agnic@latest x402 details *)"]
 ---
 
-# Search for Service
+# Searching the x402 Bazaar
 
-Discover x402-enabled APIs that can be paid for using AgnicPay.
+Use the `npx agnic@latest x402` commands to discover and inspect paid API endpoints available on the x402 bazaar marketplace. No authentication or balance is required for searching.
 
-## Steps
+## Commands
 
-1. Search for APIs matching the user's query:
-   ```bash
-   npx agnic@latest x402 search "<query>" --json
-   ```
+### Search the Bazaar
 
-2. Optionally filter by category:
-   ```bash
-   npx agnic@latest x402 search "<query>" --category AI --json
-   ```
+Find paid services by keyword using BM25 relevance search:
 
-3. Present the results to the user with names, descriptions, prices, and URLs.
+```bash
+npx agnic@latest x402 bazaar search <query> [-k <n>] [--force-refresh] [--json]
+```
+
+| Option            | Description                          |
+| ----------------- | ------------------------------------ |
+| `-k, --top <n>`   | Number of results (default: 5)       |
+| `--force-refresh` | Re-fetch resource index from CDP API |
+| `--json`          | Output as JSON                       |
+
+Results are cached locally at `~/.config/agnic/bazaar/` and auto-refresh after 12 hours.
+
+### List Bazaar Resources
 
-## Parameters
+Browse all available resources:
 
-- `<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)
+```bash
+npx agnic@latest x402 bazaar list [--network <network>] [--full] [--json]
+```
+
+| Option             | Description                             |
+| ------------------ | --------------------------------------- |
+| `--network <name>` | Filter by network (base, base-sepolia)  |
+| `--full`           | Show complete details including schemas |
+| `--json`           | Output as JSON                          |
 
-## Example
+### Discover Payment Requirements
+
+Inspect an endpoint's x402 payment requirements without paying:
 
 ```bash
-npx agnic@latest x402 search "sentiment analysis" --category AI --json
+npx agnic@latest x402 details <url> [--json]
 ```
 
-## Expected Output
-
-```json
-{
-  "apis": [
-    {
-      "name": "Sentiment Pro",
-      "description": "Real-time sentiment analysis",
-      "price": "0.001",
-      "url": "https://api.example.com/sentiment"
-    }
-  ]
-}
+Auto-detects the correct HTTP method (GET, POST, PUT, DELETE, PATCH) by trying each until it gets a 402 response, then displays price, accepted payment schemes, network, and input/output schemas.
+
+## Examples
+
+```bash
+# Search for weather-related paid APIs
+npx agnic@latest x402 bazaar search "weather"
+
+# Search with more results
+npx agnic@latest x402 bazaar search "sentiment analysis" -k 10
+
+# Browse all bazaar resources with full details
+npx agnic@latest x402 bazaar list --full
+
+# Check what an endpoint costs
+npx agnic@latest x402 details https://example.com/api/weather
 ```
 
+## Prerequisites
+
+- No authentication needed for search, list, or details commands
+
+## Next Steps
+
+Once you've found a service you want to use, use the `pay-for-service` skill to make a paid request to the endpoint.
+
 ## 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)
+Common errors:
+
+- "CDP API returned 429" — Rate limited; cached data will be used if available
+- "No X402 payment requirements found" — URL may not be an x402 endpoint
+- No results — Try broadening the search query or using different keywords