@agnic/wallet-skills 1.0.1 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (19) hide show
  1. package/.agents/skills/authenticate-wallet/SKILL.md +51 -0
  2. package/.agents/skills/check-balance/SKILL.md +51 -0
  3. package/.agents/skills/fund-wallet/SKILL.md +46 -0
  4. package/.agents/skills/get-agent-identity/SKILL.md +52 -0
  5. package/.agents/skills/pay-for-service/SKILL.md +67 -0
  6. package/.agents/skills/search-for-service/SKILL.md +57 -0
  7. package/.agents/skills/send-usdc/SKILL.md +61 -0
  8. package/.agents/skills/trade-tokens/SKILL.md +78 -0
  9. package/README.md +39 -31
  10. package/package.json +8 -13
  11. package/skills/authenticate-wallet/SKILL.md +74 -0
  12. package/skills/check-balance/SKILL.md +75 -0
  13. package/skills/fund-wallet/SKILL.md +79 -0
  14. package/skills/get-agent-identity/SKILL.md +79 -0
  15. package/skills/pay-for-service/SKILL.md +109 -0
  16. package/skills/search-for-service/SKILL.md +85 -0
  17. package/skills/send-usdc/SKILL.md +96 -0
  18. package/skills/trade-tokens/SKILL.md +107 -0
  19. package/skills-lock.json +45 -0
package/.agents/skills/authenticate-wallet/SKILL.md ADDED
@@ -0,0 +1,51 @@
1
+ ---
2
+ name: authenticate-wallet
3
+ description: Sign in to AgnicPay wallet via browser-based OAuth
4
+ user-invocable: true
5
+ disable-model-invocation: false
6
+ allowed-tools: ["Bash(npx agnic@latest *)"]
7
+ ---
8
+
9
+ # Authenticate Wallet
10
+
11
+ Authenticate the user with their AgnicPay wallet using browser-based OAuth login.
12
+
13
+ ## Steps
14
+
15
+ 1. Run the login command:
16
+ ```bash
17
+ npx agnic@latest auth login
18
+ ```
19
+ This opens the user's browser to AgnicPay where they sign in and set spending limits.
20
+
21
+ 2. Wait for the browser flow to complete. The CLI will show "Authenticated!" when done.
22
+
23
+ 3. Verify authentication:
24
+ ```bash
25
+ npx agnic@latest status --json
26
+ ```
27
+
28
+ ## Expected Output
29
+
30
+ ```json
31
+ {
32
+ "authenticated": true,
33
+ "userId": "did:privy:...",
34
+ "email": "user@example.com",
35
+ "walletAddress": "0x...",
36
+ "tokenExpiry": "2026-05-22T..."
37
+ }
38
+ ```
39
+
40
+ ## Error Handling
41
+
42
+ - If the user cancels the browser flow, the CLI will show "Authentication failed".
43
+ - If the browser doesn't open, the CLI prints a URL the user can copy manually.
44
+ - If already authenticated, `agnic status` will confirm without re-login.
45
+
46
+ ## Logout
47
+
48
+ To remove stored credentials:
49
+ ```bash
50
+ npx agnic@latest auth logout
51
+ ```
package/.agents/skills/check-balance/SKILL.md ADDED
@@ -0,0 +1,51 @@
1
+ ---
2
+ name: check-balance
3
+ description: Check USDC balance across networks (Base, Solana)
4
+ user-invocable: true
5
+ disable-model-invocation: false
6
+ allowed-tools: ["Bash(npx agnic@latest *)"]
7
+ ---
8
+
9
+ # Check Balance
10
+
11
+ Check the user's USDC balance across supported networks.
12
+
13
+ ## Steps
14
+
15
+ 1. Verify authentication:
16
+ ```bash
17
+ npx agnic@latest status --json
18
+ ```
19
+ If not authenticated, run `npx agnic@latest auth login` first.
20
+
21
+ 2. Check balance for all networks:
22
+ ```bash
23
+ npx agnic@latest balance --json
24
+ ```
25
+
26
+ 3. Or check a specific network:
27
+ ```bash
28
+ npx agnic@latest balance --network base --json
29
+ npx agnic@latest balance --network solana --json
30
+ ```
31
+
32
+ ## Expected Output
33
+
34
+ ```json
35
+ [
36
+ { "network": "base", "balance": "125.50", "address": "0x..." },
37
+ { "network": "solana", "balance": "0", "address": "N/A" }
38
+ ]
39
+ ```
40
+
41
+ ## Supported Networks
42
+
43
+ - `base` — Base mainnet (EVM, primary)
44
+ - `solana` — Solana mainnet
45
+ - `base-sepolia` — Base testnet
46
+ - `solana-devnet` — Solana devnet
47
+
48
+ ## Error Handling
49
+
50
+ - If not authenticated: prompt user to run `npx agnic@latest auth login`
51
+ - If a network returns an error, report it and show available balances
package/.agents/skills/fund-wallet/SKILL.md ADDED
@@ -0,0 +1,46 @@
1
+ ---
2
+ name: fund-wallet
3
+ description: Get instructions for funding your AgnicPay wallet
4
+ user-invocable: true
5
+ disable-model-invocation: false
6
+ allowed-tools: ["Bash(npx agnic@latest *)"]
7
+ ---
8
+
9
+ # Fund Wallet
10
+
11
+ Provide instructions for adding funds to the user's AgnicPay wallet.
12
+
13
+ ## Steps
14
+
15
+ 1. Check if the user is authenticated:
16
+ ```bash
17
+ npx agnic@latest status --json
18
+ ```
19
+
20
+ 2. Show the user's wallet address:
21
+ ```bash
22
+ npx agnic@latest address --json
23
+ ```
24
+
25
+ 3. Explain funding options:
26
+
27
+ **Option 1: AgnicPay Dashboard**
28
+ - Go to [pay.agnic.ai](https://pay.agnic.ai)
29
+ - Navigate to your dashboard
30
+ - Use the "Add Funds" feature to deposit USDC
31
+
32
+ **Option 2: Direct Transfer**
33
+ - Send USDC to your wallet address on Base network
34
+ - The address is shown by `agnic address`
35
+ - Use any wallet (MetaMask, Coinbase, etc.) to send USDC on Base
36
+
37
+ 4. After funding, verify the balance:
38
+ ```bash
39
+ npx agnic@latest balance --json
40
+ ```
41
+
42
+ ## Important Notes
43
+
44
+ - AgnicPay wallets use USDC (not ETH) for payments and trading
45
+ - Base network is the primary chain
46
+ - Minimum recommended balance: $1.00 USDC for testing
package/.agents/skills/get-agent-identity/SKILL.md ADDED
@@ -0,0 +1,52 @@
1
+ ---
2
+ name: get-agent-identity
3
+ description: Check your agent's on-chain ERC-8004 identity and trust score
4
+ user-invocable: true
5
+ disable-model-invocation: false
6
+ allowed-tools: ["Bash(npx agnic@latest *)"]
7
+ ---
8
+
9
+ # Get Agent Identity
10
+
11
+ Check the user's on-chain ERC-8004 agent identity, trust score, and KYA credentials.
12
+
13
+ ## Steps
14
+
15
+ 1. Verify authentication:
16
+ ```bash
17
+ npx agnic@latest status --json
18
+ ```
19
+
20
+ 2. Check agent identity:
21
+ ```bash
22
+ npx agnic@latest agent-identity --json
23
+ ```
24
+ Note: If `agent-identity` is not available, use the API directly:
25
+ ```bash
26
+ npx agnic@latest x402 pay "https://api.agnic.ai/api/agent/identity" --method GET --json
27
+ ```
28
+
29
+ ## What is ERC-8004?
30
+
31
+ ERC-8004 ("Trustless Agents") is an Ethereum standard that gives AI agents:
32
+ - **On-chain identity** — An NFT representing the agent
33
+ - **Reputation score** — Trust score based on transaction history
34
+ - **Verifiable credentials** — KYA (Know Your Agent) credentials for identity verification
35
+
36
+ ## Expected Output
37
+
38
+ ```json
39
+ {
40
+ "agentId": 373,
41
+ "ownerAddress": "0x046906b3...",
42
+ "status": "active",
43
+ "registeredAt": "2024-12-15T...",
44
+ "trustScore": 85,
45
+ "categories": ["payment", "general"]
46
+ }
47
+ ```
48
+
49
+ ## Error Handling
50
+
51
+ - If the user doesn't have an agent identity, they can create one via the AgnicPay dashboard
52
+ - Agent identity is automatically created during OAuth sign-up
package/.agents/skills/pay-for-service/SKILL.md ADDED
@@ -0,0 +1,67 @@
1
+ ---
2
+ name: pay-for-service
3
+ description: Make paid requests to x402-enabled APIs
4
+ user-invocable: true
5
+ disable-model-invocation: false
6
+ allowed-tools: ["Bash(npx agnic@latest *)"]
7
+ ---
8
+
9
+ # Pay for Service
10
+
11
+ Make a paid x402 request to an API endpoint. AgnicPay handles the payment automatically.
12
+
13
+ ## Steps
14
+
15
+ 1. Verify authentication:
16
+ ```bash
17
+ npx agnic@latest status --json
18
+ ```
19
+
20
+ 2. Check balance to ensure sufficient funds:
21
+ ```bash
22
+ npx agnic@latest balance --network base --json
23
+ ```
24
+
25
+ 3. Make the x402 payment request:
26
+ ```bash
27
+ npx agnic@latest x402 pay "<url>" --json
28
+ ```
29
+
30
+ 4. For POST requests with a body:
31
+ ```bash
32
+ npx agnic@latest x402 pay "<url>" --method POST --body '{"key": "value"}' --json
33
+ ```
34
+
35
+ ## Parameters
36
+
37
+ - `<url>` — Full URL of the x402-enabled API endpoint
38
+ - `--method` — HTTP method (default: GET)
39
+ - `--body` — Request body as JSON string (for POST/PUT)
40
+
41
+ ## Example
42
+
43
+ ```bash
44
+ npx agnic@latest x402 pay "https://api.example.com/analysis" \
45
+ --method POST \
46
+ --body '{"query": "latest market data"}' \
47
+ --json
48
+ ```
49
+
50
+ ## Expected Output
51
+
52
+ ```json
53
+ {
54
+ "status": 200,
55
+ "cost": "0.001",
56
+ "network": "base",
57
+ "transactionHash": "0xabc123...",
58
+ "data": { "result": "..." }
59
+ }
60
+ ```
61
+
62
+ ## Error Handling
63
+
64
+ - If not authenticated: prompt user to run `npx agnic@latest auth login`
65
+ - If balance is insufficient, inform the user and suggest funding
66
+ - If the API returns an error, show the status code and response body
67
+ - The `--body` flag must be valid JSON; if invalid, the CLI will report the parse error
package/.agents/skills/search-for-service/SKILL.md ADDED
@@ -0,0 +1,57 @@
1
+ ---
2
+ name: search-for-service
3
+ description: Search for x402-enabled APIs and services
4
+ user-invocable: true
5
+ disable-model-invocation: false
6
+ allowed-tools: ["Bash(npx agnic@latest *)"]
7
+ ---
8
+
9
+ # Search for Service
10
+
11
+ Discover x402-enabled APIs that can be paid for using AgnicPay.
12
+
13
+ ## Steps
14
+
15
+ 1. Search for APIs matching the user's query:
16
+ ```bash
17
+ npx agnic@latest x402 search "<query>" --json
18
+ ```
19
+
20
+ 2. Optionally filter by category:
21
+ ```bash
22
+ npx agnic@latest x402 search "<query>" --category AI --json
23
+ ```
24
+
25
+ 3. Present the results to the user with names, descriptions, prices, and URLs.
26
+
27
+ ## Parameters
28
+
29
+ - `<query>` — Search term (e.g., "sentiment analysis", "weather data")
30
+ - `--category` — Filter by category: AI, Crypto, Data, Trading, Finance, Weather
31
+ - `--limit <n>` — Max results (default: 10)
32
+
33
+ ## Example
34
+
35
+ ```bash
36
+ npx agnic@latest x402 search "sentiment analysis" --category AI --json
37
+ ```
38
+
39
+ ## Expected Output
40
+
41
+ ```json
42
+ {
43
+ "apis": [
44
+ {
45
+ "name": "Sentiment Pro",
46
+ "description": "Real-time sentiment analysis",
47
+ "price": "0.001",
48
+ "url": "https://api.example.com/sentiment"
49
+ }
50
+ ]
51
+ }
52
+ ```
53
+
54
+ ## Error Handling
55
+
56
+ - If no results found, suggest broadening the search or trying different keywords
57
+ - Authentication is NOT required for search (it's a public endpoint)
package/.agents/skills/send-usdc/SKILL.md ADDED
@@ -0,0 +1,61 @@
1
+ ---
2
+ name: send-usdc
3
+ description: Send USDC to a wallet address on Base or Solana
4
+ user-invocable: true
5
+ disable-model-invocation: false
6
+ allowed-tools: ["Bash(npx agnic@latest *)"]
7
+ ---
8
+
9
+ # Send USDC
10
+
11
+ Send USDC from the user's wallet to a recipient address.
12
+
13
+ ## Steps
14
+
15
+ 1. Verify authentication:
16
+ ```bash
17
+ npx agnic@latest status --json
18
+ ```
19
+
20
+ 2. Check balance to ensure sufficient funds:
21
+ ```bash
22
+ npx agnic@latest balance --network base --json
23
+ ```
24
+
25
+ 3. Confirm with the user: the amount, recipient address, and network.
26
+
27
+ 4. Send USDC:
28
+ ```bash
29
+ npx agnic@latest send <amount> <recipient_address> --network base --json
30
+ ```
31
+
32
+ ## Parameters
33
+
34
+ - `<amount>` — Amount in USDC (e.g., `5.00`)
35
+ - `<recipient_address>` — Destination wallet address (0x... for EVM)
36
+ - `--network` — Network to send on (default: `base`)
37
+ - `--memo` — Optional transaction memo
38
+
39
+ ## Example
40
+
41
+ ```bash
42
+ npx agnic@latest send 5.00 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7 --network base --json
43
+ ```
44
+
45
+ ## Expected Output
46
+
47
+ ```json
48
+ {
49
+ "amount": "5.00",
50
+ "to": "0x742d35Cc...",
51
+ "network": "base",
52
+ "transactionHash": "0xabc123...",
53
+ "explorerUrl": "https://basescan.org/tx/0xabc123..."
54
+ }
55
+ ```
56
+
57
+ ## Error Handling
58
+
59
+ - If balance is insufficient, inform the user and suggest funding their wallet
60
+ - Always confirm the recipient address and amount before sending
61
+ - If the transaction fails, show the error message from the API
package/.agents/skills/trade-tokens/SKILL.md ADDED
@@ -0,0 +1,78 @@
1
+ ---
2
+ name: trade-tokens
3
+ description: Trade/swap tokens on Base (USDC, ETH, WETH, cbETH, DAI, AERO)
4
+ user-invocable: true
5
+ disable-model-invocation: false
6
+ allowed-tools: ["Bash(npx agnic@latest *)"]
7
+ ---
8
+
9
+ # Trade Tokens
10
+
11
+ Swap tokens on Base mainnet using AgnicPay's DEX integration.
12
+
13
+ ## Steps
14
+
15
+ 1. Verify authentication:
16
+ ```bash
17
+ npx agnic@latest status --json
18
+ ```
19
+
20
+ 2. Check balance to ensure sufficient funds:
21
+ ```bash
22
+ npx agnic@latest balance --network base --json
23
+ ```
24
+
25
+ 3. Preview the trade (optional but recommended):
26
+ ```bash
27
+ npx agnic@latest trade <amount> <sell_token> <buy_token> --dry-run --json
28
+ ```
29
+
30
+ 4. Confirm with the user: amount, tokens, and estimated output.
31
+
32
+ 5. Execute the trade:
33
+ ```bash
34
+ npx agnic@latest trade <amount> <sell_token> <buy_token> --json
35
+ ```
36
+
37
+ ## Supported Tokens
38
+
39
+ USDC, ETH, WETH, cbETH, DAI, AERO (case-insensitive)
40
+
41
+ ## Parameters
42
+
43
+ - `<amount>` — Amount of the sell token
44
+ - `<sell_token>` — Token to sell (e.g., `usdc`)
45
+ - `<buy_token>` — Token to buy (e.g., `eth`)
46
+ - `--slippage <percent>` — Max slippage (default: `1.0`)
47
+ - `--dry-run` — Show quote without executing
48
+
49
+ ## Example
50
+
51
+ ```bash
52
+ # Preview
53
+ npx agnic@latest trade 10 usdc eth --dry-run --json
54
+
55
+ # Execute
56
+ npx agnic@latest trade 10 usdc eth --json
57
+ ```
58
+
59
+ ## Expected Output
60
+
61
+ ```json
62
+ {
63
+ "success": true,
64
+ "sellAmount": "10",
65
+ "sellToken": "USDC",
66
+ "buyAmount": "0.00396",
67
+ "buyToken": "ETH",
68
+ "price": "2525.25",
69
+ "transactionHash": "0xabc123...",
70
+ "explorerUrl": "https://basescan.org/tx/0xabc123..."
71
+ }
72
+ ```
73
+
74
+ ## Error Handling
75
+
76
+ - Always preview with `--dry-run` first to show the user expected output
77
+ - If slippage is too high, suggest a lower amount or higher slippage tolerance
78
+ - Trading is only available on Base mainnet
package/README.md CHANGED
@@ -1,50 +1,58 @@
1
- # @agnic/wallet-skills
1
+ # AgnicPay Agentic Wallet Skills
2
2
 
3
- Pre-built AI agent skills for [AgnicPay](https://pay.agnic.ai) — x402 payments, token trading, and identity.
3
+ 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.
4
4
 
5
- Compatible with the [Vercel AI SDK](https://sdk.vercel.ai) skills system.
5
+ ## Available Skills
6
+
7
+ | Skill | Description |
8
+ |-------|-------------|
9
+ | **authenticate-wallet** | Sign in to the wallet via browser OAuth |
10
+ | **check-balance** | Check USDC balance across networks (Base, Solana) |
11
+ | **send-usdc** | Send USDC to Ethereum wallet addresses |
12
+ | **trade-tokens** | Swap/trade tokens on Base (USDC, ETH, WETH, cbETH, DAI, AERO) |
13
+ | **search-for-service** | Search for paid API services via x402 |
14
+ | **pay-for-service** | Make paid API requests via x402 |
15
+ | **fund-wallet** | Get instructions for adding funds to the wallet |
16
+ | **get-agent-identity** | Check on-chain ERC-8004 identity and trust score |
17
+
18
+ ## Installation
6
19
 
7
- ## Install
20
+ Install with Vercel's [Skills CLI](https://github.com/vercel/skills):
8
21
 
9
22
  ```bash
10
- npx skills add @agnic/wallet-skills
23
+ npx skills add agnicpay/agnic-wallet-skills
11
24
  ```
12
25
 
13
- ## Available Skills
26
+ ## Usage
14
27
 
15
- | Skill | Trigger Phrases | What It Does |
16
- |-------|-----------------|--------------|
17
- | **authenticate-wallet** | "log in", "sign in" | Email OTP login flow |
18
- | **check-balance** | "check balance", "how much do I have" | USDC balance across networks |
19
- | **send-usdc** | "send", "transfer", "pay someone" | Send USDC to a wallet |
20
- | **trade-tokens** | "trade", "swap", "buy ETH" | Swap tokens on Base |
21
- | **search-for-service** | "find an API", "search for" | Discover x402-enabled APIs |
22
- | **pay-for-service** | "call this API", "use this service" | Make x402 payment requests |
23
- | **fund-wallet** | "add funds", "deposit" | Instructions for funding |
24
- | **get-agent-identity** | "agent identity", "trust score" | ERC-8004 identity & credentials |
28
+ Skills are automatically available once installed. The agent will use them when relevant tasks are detected.
25
29
 
26
- ## Prerequisites
30
+ Examples:
27
31
 
28
- Skills use the `agnic` CLI under the hood:
32
+ - `Sign in to my wallet`
33
+ - `Check my balance`
34
+ - `Send 10 USDC to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7`
35
+ - `Swap 5 USDC for ETH`
36
+ - `Find a sentiment analysis API`
37
+ - `Pay for https://api.example.com/data`
38
+ - `What's my agent identity?`
29
39
 
30
- ```bash
31
- npm install -g agnic
32
- agnic auth login you@example.com
33
- ```
40
+ ## Contributing
34
41
 
35
- ## How It Works
42
+ To add a new skill:
36
43
 
37
- Each skill is a markdown instruction file that teaches AI assistants how to complete wallet tasks using CLI commands. When a user's request matches a skill, the AI follows the instructions automatically.
44
+ 1. Create a folder in `./skills/` with a lowercase, hyphenated name
45
+ 2. Add a `SKILL.md` file with YAML frontmatter and instructions
46
+ 3. See the [Agent Skills specification](https://github.com/vercel/skills) for the complete format
38
47
 
39
- **Example:** User says "swap 10 USDC for ETH" → `trade-tokens` skill runs:
40
- ```bash
41
- agnic balance --network base --json
42
- agnic trade 10 usdc eth --json
43
- ```
48
+ ### Updating the agnic version
44
49
 
45
- ## Unique: Agent Identity
50
+ All skills pin `agnic@latest` via `npx agnic@latest`. When testing against a specific version:
46
51
 
47
- The `get-agent-identity` skill has no equivalent in other wallet tools. It lets AI agents check their on-chain [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) identity, trust score, and KYA credentials.
52
+ ```bash
53
+ # Install a specific version
54
+ npm install -g agnic@2.0.0
55
+ ```
48
56
 
49
57
  ## Documentation
50
58
 
package/package.json CHANGED
@@ -1,25 +1,20 @@
1
1
  {
2
2
  "name": "@agnic/wallet-skills",
3
- "version": "1.0.1",
4
- "description": "AI agent wallet skills for x402 payments, token trading, and identity",
5
- "skills": "skills/",
6
- "files": [
7
- "skills/",
8
- "README.md"
9
- ],
3
+ "version": "1.2.0",
4
+ "description": "Vercel AI SDK skills for AgnicPay wallet — balance, payments, trading, x402, and agent identity",
10
5
  "keywords": [
11
- "vercel-ai-skills",
6
+ "agnic",
7
+ "agnicpay",
8
+ "skills",
9
+ "vercel-ai",
12
10
  "x402",
13
11
  "wallet",
14
- "ai-agent",
15
- "trading",
16
- "erc-8004",
17
- "agnicpay"
12
+ "ai-agent"
18
13
  ],
19
14
  "license": "MIT",
20
15
  "repository": {
21
16
  "type": "git",
22
- "url": "https://github.com/agnicpay/agnic-wallet-skills"
17
+ "url": "https://github.com/agnic-protocol/agnic-wallet-skills"
23
18
  },
24
19
  "homepage": "https://docs.agnic.ai/docs/agnicpay-features/skills"
25
20
  }
package/skills/authenticate-wallet/SKILL.md ADDED
@@ -0,0 +1,74 @@
1
+ ---
2
+ name: authenticate-wallet
3
+ 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".
4
+ user-invocable: true
5
+ disable-model-invocation: false
6
+ allowed-tools: ["Bash(npx agnic@latest status*)", "Bash(npx agnic@latest auth *)"]
7
+ ---
8
+
9
+ # Authenticating the AgnicPay Wallet
10
+
11
+ 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.
12
+
13
+ ## Confirm wallet is initialized and authed
14
+
15
+ ```bash
16
+ npx agnic@latest status
17
+ ```
18
+
19
+ If already authenticated, no further action is needed. If not authenticated, proceed with login.
20
+
21
+ ## Login Flow
22
+
23
+ ```bash
24
+ npx agnic@latest auth login
25
+ ```
26
+
27
+ This command:
28
+ 1. Starts a temporary local server on a random port
29
+ 2. Opens the user's default browser to AgnicPay's OAuth consent screen
30
+ 3. The user signs in (email, Google, or wallet) and approves spending limits
31
+ 4. The browser redirects back to `http://localhost:<port>/callback`
32
+ 5. The CLI exchanges the authorization code for tokens and saves them locally
33
+
34
+ Wait for the CLI to print `✓ Authenticated!` before proceeding.
35
+
36
+ ## Verify Authentication
37
+
38
+ After login, confirm the session is active:
39
+
40
+ ```bash
41
+ npx agnic@latest status
42
+ ```
43
+
44
+ Expected output:
45
+
46
+ ```
47
+ Wallet Status
48
+ ✓ Authenticated
49
+
50
+ Email: user@example.com
51
+ Wallet: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7
52
+ Expires: 2026-05-22 14:30:00 UTC
53
+ ```
54
+
55
+ ## Logout
56
+
57
+ To remove stored credentials:
58
+
59
+ ```bash
60
+ npx agnic@latest auth logout
61
+ ```
62
+
63
+ ## Token Storage
64
+
65
+ 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).
66
+
67
+ ## Error Handling
68
+
69
+ Common errors:
70
+
71
+ - "Not authenticated" — Run `npx agnic@latest auth login`
72
+ - "Authentication failed" — User cancelled the browser flow or the timeout (5 min) expired
73
+ - "Could not open browser" — The CLI prints a URL to copy and open manually
74
+ - "Token expired" — Tokens auto-refresh; if refresh also fails, re-run `npx agnic@latest auth login`
package/skills/check-balance/SKILL.md ADDED
@@ -0,0 +1,75 @@
1
+ ---
2
+ name: check-balance
3
+ 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".
4
+ user-invocable: true
5
+ disable-model-invocation: false
6
+ allowed-tools: ["Bash(npx agnic@latest status*)", "Bash(npx agnic@latest balance*)"]
7
+ ---
8
+
9
+ # Checking USDC Balance
10
+
11
+ Use the `npx agnic@latest balance` command to check USDC balance across supported networks.
12
+
13
+ ## Confirm wallet is initialized and authed
14
+
15
+ ```bash
16
+ npx agnic@latest status
17
+ ```
18
+
19
+ If the wallet is not authenticated, refer to the `authenticate-wallet` skill.
20
+
21
+ ## Command Syntax
22
+
23
+ ```bash
24
+ npx agnic@latest balance [--network <network>] [--json]
25
+ ```
26
+
27
+ ## Options
28
+
29
+ | Option | Description |
30
+ | -------------------- | ------------------------------------------ |
31
+ | `--network <name>` | Filter by network (default: all networks) |
32
+ | `--json` | Output result as JSON |
33
+
34
+ ## Supported Networks
35
+
36
+ | Network | Description |
37
+ | -------------- | --------------------- |
38
+ | `base` | Base mainnet (primary) |
39
+ | `base-sepolia` | Base testnet |
40
+ | `solana` | Solana mainnet |
41
+ | `solana-devnet`| Solana devnet |
42
+
43
+ ## Examples
44
+
45
+ ```bash
46
+ # Check balance on all networks
47
+ npx agnic@latest balance
48
+
49
+ # Check balance on Base mainnet only
50
+ npx agnic@latest balance --network base
51
+
52
+ # Get JSON output
53
+ npx agnic@latest balance --json
54
+ ```
55
+
56
+ ## Expected Output
57
+
58
+ ```
59
+ Network Balance Address
60
+ base 125.50 USDC 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7
61
+ base-sepolia 0.00 USDC 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7
62
+ solana 0.00 USDC N/A
63
+ solana-devnet 0.00 USDC N/A
64
+ ```
65
+
66
+ ## Prerequisites
67
+
68
+ - Must be authenticated (`npx agnic@latest status` to check)
69
+
70
+ ## Error Handling
71
+
72
+ Common errors:
73
+
74
+ - "Not authenticated" — Run `npx agnic@latest auth login` first
75
+ - Network timeout — Try again or specify a single network with `--network base`
package/skills/fund-wallet/SKILL.md ADDED
@@ -0,0 +1,79 @@
1
+ ---
2
+ name: fund-wallet
3
+ 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".
4
+ user-invocable: true
5
+ disable-model-invocation: false
6
+ allowed-tools: ["Bash(npx agnic@latest status*)", "Bash(npx agnic@latest address*)", "Bash(npx agnic@latest balance*)"]
7
+ ---
8
+
9
+ # Funding the AgnicPay Wallet
10
+
11
+ Provide instructions for adding USDC to the user's AgnicPay wallet on Base.
12
+
13
+ ## Confirm wallet is initialized and authed
14
+
15
+ ```bash
16
+ npx agnic@latest status
17
+ ```
18
+
19
+ If the wallet is not authenticated, refer to the `authenticate-wallet` skill.
20
+
21
+ ## Get Wallet Address
22
+
23
+ ```bash
24
+ npx agnic@latest address
25
+ ```
26
+
27
+ This displays the user's wallet address on each supported network.
28
+
29
+ ## Funding Options
30
+
31
+ ### Option 1: AgnicPay Dashboard (Recommended)
32
+
33
+ 1. Go to [pay.agnic.ai](https://pay.agnic.ai)
34
+ 2. Sign in with the same account used in the CLI
35
+ 3. Navigate to the dashboard
36
+ 4. Use the **"Add Funds"** button to deposit USDC via card, bank transfer, or crypto
37
+
38
+ ### Option 2: Direct USDC Transfer
39
+
40
+ Send USDC directly to the wallet address on **Base network**:
41
+
42
+ 1. Get the address: `npx agnic@latest address`
43
+ 2. From any wallet (MetaMask, Coinbase, Phantom, etc.), send USDC on **Base** to that address
44
+ 3. Verify arrival: `npx agnic@latest balance --network base`
45
+
46
+ **Important**: Send USDC on **Base network** only. USDC on other chains (Ethereum mainnet, Arbitrum, etc.) will not appear in the AgnicPay balance.
47
+
48
+ ### Option 3: Bridge from Another Chain
49
+
50
+ If the user has USDC on Ethereum, Arbitrum, or Optimism, they can bridge to Base using:
51
+ - [bridge.base.org](https://bridge.base.org) (official Base bridge)
52
+ - Any cross-chain bridge that supports Base
53
+
54
+ ## Verify Balance
55
+
56
+ After funding, confirm the deposit arrived:
57
+
58
+ ```bash
59
+ npx agnic@latest balance --network base
60
+ ```
61
+
62
+ ## Important Notes
63
+
64
+ - AgnicPay wallets use **USDC** (not ETH) for payments and trading
65
+ - **Base network** is the primary chain
66
+ - Minimum recommended balance: **$1.00 USDC** for testing
67
+ - Small amounts of ETH on Base may be needed for gas (auto-handled in most cases)
68
+
69
+ ## Prerequisites
70
+
71
+ - Must be authenticated (`npx agnic@latest status` to check)
72
+
73
+ ## Error Handling
74
+
75
+ Common errors:
76
+
77
+ - "Not authenticated" — Run `npx agnic@latest auth login` first
78
+ - Balance shows 0 after transfer — Verify the transfer was on Base network (not Ethereum mainnet)
79
+ - Transfer pending — Base transactions typically confirm in 2-3 seconds
package/skills/get-agent-identity/SKILL.md ADDED
@@ -0,0 +1,79 @@
1
+ ---
2
+ name: get-agent-identity
3
+ 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".
4
+ user-invocable: true
5
+ disable-model-invocation: false
6
+ allowed-tools: ["Bash(npx agnic@latest status*)", "Bash(npx agnic@latest agent-identity*)"]
7
+ ---
8
+
9
+ # Getting Agent Identity
10
+
11
+ Check the user's on-chain ERC-8004 agent identity, trust score, and KYA (Know Your Agent) credentials.
12
+
13
+ ## Confirm wallet is initialized and authed
14
+
15
+ ```bash
16
+ npx agnic@latest status
17
+ ```
18
+
19
+ If the wallet is not authenticated, refer to the `authenticate-wallet` skill.
20
+
21
+ ## Check Agent Identity
22
+
23
+ ```bash
24
+ npx agnic@latest agent-identity --json
25
+ ```
26
+
27
+ This returns the agent's on-chain identity including:
28
+ - **Agent ID** — The ERC-721 token ID on the ERC-8004 Identity Registry
29
+ - **Owner address** — The wallet that owns the agent NFT
30
+ - **Trust score** — Reputation score (0-100) based on transaction history
31
+ - **Categories** — Authorized action categories (e.g., payment, general, alcohol)
32
+ - **Status** — Whether the agent is active or suspended
33
+
34
+ ## What is ERC-8004?
35
+
36
+ ERC-8004 ("Trustless Agents") is an Ethereum standard that gives AI agents:
37
+
38
+ | Feature | Description |
39
+ | ------- | ----------- |
40
+ | **On-chain identity** | An ERC-721 NFT representing the agent on the Identity Registry |
41
+ | **Reputation score** | Trust score (0-100) based on on-chain transaction history |
42
+ | **KYA credentials** | SD-JWT verifiable credentials for identity verification |
43
+ | **Delegation** | Spending limits and category permissions via KYA delegation credentials |
44
+
45
+ ## Contract Addresses
46
+
47
+ | Contract | Network | Address |
48
+ | -------- | ------- | ------- |
49
+ | Identity Registry | Base Mainnet | `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432` |
50
+ | Identity Registry | Base Sepolia | `0x8004A818BFB912233c491871b3d84c89A494BD9e` |
51
+ | Reputation | Base Mainnet | `0x8004BAa17C55a88189AE136b182e5fdA19dE9b63` |
52
+ | Reputation | Base Sepolia | `0x8004B663056A597Dffe9eCcC1965A193B7388713` |
53
+
54
+ ## Expected Output
55
+
56
+ ```json
57
+ {
58
+ "agentId": 373,
59
+ "ownerAddress": "0x046906b3cd9d73bf85eb01d795d333b364b75842",
60
+ "status": "active",
61
+ "registeredAt": "2024-12-15T10:30:00Z",
62
+ "trustScore": 85,
63
+ "categories": ["payment", "general"],
64
+ "hasDelegation": true
65
+ }
66
+ ```
67
+
68
+ ## Prerequisites
69
+
70
+ - Must be authenticated (`npx agnic@latest status` to check)
71
+ - Agent identity is automatically created during AgnicPay sign-up
72
+
73
+ ## Error Handling
74
+
75
+ Common errors:
76
+
77
+ - "Not authenticated" — Run `npx agnic@latest auth login` first
78
+ - "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)
79
+ - "Agent suspended" — The agent's delegation may have been revoked; contact support
package/skills/pay-for-service/SKILL.md ADDED
@@ -0,0 +1,109 @@
1
+ ---
2
+ name: pay-for-service
3
+ 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".
4
+ user-invocable: true
5
+ disable-model-invocation: false
6
+ allowed-tools: ["Bash(npx agnic@latest status*)", "Bash(npx agnic@latest x402 pay *)", "Bash(npx agnic@latest x402 details *)", "Bash(npx agnic@latest balance*)"]
7
+ ---
8
+
9
+ # Paying for x402 Services
10
+
11
+ Use the `npx agnic@latest x402 pay` command to call x402-enabled API endpoints with automatic USDC payment on Base.
12
+
13
+ ## Confirm wallet is initialized and authed
14
+
15
+ ```bash
16
+ npx agnic@latest status
17
+ ```
18
+
19
+ If the wallet is not authenticated, refer to the `authenticate-wallet` skill.
20
+
21
+ ## Command Syntax
22
+
23
+ ```bash
24
+ npx agnic@latest x402 pay <url> [-X <method>] [-d <json>] [-q <params>] [-h <json>] [--max-amount <n>] [--json]
25
+ ```
26
+
27
+ ## Arguments & Options
28
+
29
+ | Option | Description |
30
+ | ----------------------- | -------------------------------------------------- |
31
+ | `<url>` | Full URL of the x402-enabled API endpoint |
32
+ | `-X, --method <method>` | HTTP method (default: GET) |
33
+ | `-d, --data <json>` | Request body as JSON string |
34
+ | `-q, --query <params>` | Query parameters as JSON string |
35
+ | `-h, --headers <json>` | Custom HTTP headers as JSON string |
36
+ | `--max-amount <amount>` | Max payment in USDC atomic units (1000000 = $1.00) |
37
+ | `--correlation-id <id>` | Group related operations |
38
+ | `--json` | Output as JSON |
39
+
40
+ ## USDC Amounts
41
+
42
+ X402 uses USDC atomic units (6 decimals):
43
+
44
+ | Atomic Units | USD |
45
+ | ------------ | ----- |
46
+ | 1000000 | $1.00 |
47
+ | 100000 | $0.10 |
48
+ | 50000 | $0.05 |
49
+ | 10000 | $0.01 |
50
+
51
+ ## Input Validation
52
+
53
+ Before constructing the command, validate:
54
+
55
+ - **url**: Must be a valid HTTPS URL (`^https://[^\s;|&]+$`). Reject URLs containing spaces, semicolons, pipes, or backticks.
56
+ - **method**: Must be one of GET, POST, PUT, DELETE, PATCH (case-insensitive).
57
+ - **data**: Must be valid JSON. Parse it first; reject if parsing fails.
58
+ - **max-amount**: Must be a positive integer (`^\d+$`).
59
+
60
+ Do not pass unvalidated user input into the command.
61
+
62
+ ## Workflow
63
+
64
+ 1. **Check requirements first** (optional but recommended):
65
+ ```bash
66
+ npx agnic@latest x402 details <url>
67
+ ```
68
+ This shows the price, method, and schema without making a payment.
69
+
70
+ 2. **Verify balance**:
71
+ ```bash
72
+ npx agnic@latest balance --network base
73
+ ```
74
+
75
+ 3. **Make the paid request**:
76
+ ```bash
77
+ npx agnic@latest x402 pay <url> --json
78
+ ```
79
+
80
+ ## Examples
81
+
82
+ ```bash
83
+ # Make a GET request (auto-pays)
84
+ npx agnic@latest x402 pay https://example.com/api/weather
85
+
86
+ # Make a POST request with body
87
+ npx agnic@latest x402 pay https://example.com/api/sentiment -X POST -d '{"text": "I love this product"}'
88
+
89
+ # Limit max payment to $0.10
90
+ npx agnic@latest x402 pay https://example.com/api/data --max-amount 100000
91
+
92
+ # Get JSON output
93
+ npx agnic@latest x402 pay https://example.com/api/weather --json
94
+ ```
95
+
96
+ ## Prerequisites
97
+
98
+ - Must be authenticated (`npx agnic@latest auth login`)
99
+ - Wallet must have sufficient USDC balance on Base
100
+
101
+ ## Error Handling
102
+
103
+ Common errors:
104
+
105
+ - "Not authenticated" — Run `npx agnic@latest auth login` first
106
+ - "Insufficient balance" — Fund wallet with USDC (`npx agnic@latest balance` to check)
107
+ - "No X402 payment requirements found" — URL may not be an x402 endpoint
108
+ - Invalid JSON in `--data` — Ensure the body is valid JSON before passing
109
+ - HTTP 4xx/5xx from the API — Show the status code and response body to the user
package/skills/search-for-service/SKILL.md ADDED
@@ -0,0 +1,85 @@
1
+ ---
2
+ name: search-for-service
3
+ 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".
4
+ user-invocable: true
5
+ disable-model-invocation: false
6
+ allowed-tools: ["Bash(npx agnic@latest x402 bazaar *)", "Bash(npx agnic@latest x402 details *)"]
7
+ ---
8
+
9
+ # Searching the x402 Bazaar
10
+
11
+ 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.
12
+
13
+ ## Commands
14
+
15
+ ### Search the Bazaar
16
+
17
+ Find paid services by keyword using BM25 relevance search:
18
+
19
+ ```bash
20
+ npx agnic@latest x402 bazaar search <query> [-k <n>] [--force-refresh] [--json]
21
+ ```
22
+
23
+ | Option | Description |
24
+ | ----------------- | ------------------------------------ |
25
+ | `-k, --top <n>` | Number of results (default: 5) |
26
+ | `--force-refresh` | Re-fetch resource index from CDP API |
27
+ | `--json` | Output as JSON |
28
+
29
+ Results are cached locally at `~/.config/agnic/bazaar/` and auto-refresh after 12 hours.
30
+
31
+ ### List Bazaar Resources
32
+
33
+ Browse all available resources:
34
+
35
+ ```bash
36
+ npx agnic@latest x402 bazaar list [--network <network>] [--full] [--json]
37
+ ```
38
+
39
+ | Option | Description |
40
+ | ------------------ | --------------------------------------- |
41
+ | `--network <name>` | Filter by network (base, base-sepolia) |
42
+ | `--full` | Show complete details including schemas |
43
+ | `--json` | Output as JSON |
44
+
45
+ ### Discover Payment Requirements
46
+
47
+ Inspect an endpoint's x402 payment requirements without paying:
48
+
49
+ ```bash
50
+ npx agnic@latest x402 details <url> [--json]
51
+ ```
52
+
53
+ 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.
54
+
55
+ ## Examples
56
+
57
+ ```bash
58
+ # Search for weather-related paid APIs
59
+ npx agnic@latest x402 bazaar search "weather"
60
+
61
+ # Search with more results
62
+ npx agnic@latest x402 bazaar search "sentiment analysis" -k 10
63
+
64
+ # Browse all bazaar resources with full details
65
+ npx agnic@latest x402 bazaar list --full
66
+
67
+ # Check what an endpoint costs
68
+ npx agnic@latest x402 details https://example.com/api/weather
69
+ ```
70
+
71
+ ## Prerequisites
72
+
73
+ - No authentication needed for search, list, or details commands
74
+
75
+ ## Next Steps
76
+
77
+ Once you've found a service you want to use, use the `pay-for-service` skill to make a paid request to the endpoint.
78
+
79
+ ## Error Handling
80
+
81
+ Common errors:
82
+
83
+ - "CDP API returned 429" — Rate limited; cached data will be used if available
84
+ - "No X402 payment requirements found" — URL may not be an x402 endpoint
85
+ - No results — Try broadening the search query or using different keywords
package/skills/send-usdc/SKILL.md ADDED
@@ -0,0 +1,96 @@
1
+ ---
2
+ name: send-usdc
3
+ description: Send USDC to an Ethereum address or ENS name. Use when you or the user want to send money, pay someone, transfer USDC, tip, donate, or send funds to a wallet address or .eth name. Covers phrases like "send $5 to", "pay 0x...", "transfer to vitalik.eth", "tip someone", "send USDC".
4
+ user-invocable: true
5
+ disable-model-invocation: false
6
+ allowed-tools: ["Bash(npx agnic@latest status*)", "Bash(npx agnic@latest send *)", "Bash(npx agnic@latest balance*)"]
7
+ ---
8
+
9
+ # Sending USDC
10
+
11
+ Use the `npx agnic@latest send` command to transfer USDC from the wallet to any Ethereum address or ENS name on Base.
12
+
13
+ ## Confirm wallet is initialized and authed
14
+
15
+ ```bash
16
+ npx agnic@latest status
17
+ ```
18
+
19
+ If the wallet is not authenticated, refer to the `authenticate-wallet` skill.
20
+
21
+ ## Command Syntax
22
+
23
+ ```bash
24
+ npx agnic@latest send <amount> <recipient> [--chain <chain>] [--json]
25
+ ```
26
+
27
+ ## Arguments
28
+
29
+ | Argument | Description |
30
+ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
31
+ | `amount` | Amount to send: `'$1.00'`, `1.00`, or atomic units (1000000 = $1). Always single-quote amounts that use `$` to prevent bash variable expansion. If the number looks like atomic units (no decimal or > 100), treat as atomic units. |
32
+ | `recipient` | Ethereum address (0x...) or ENS name (vitalik.eth) |
33
+
34
+ ## Options
35
+
36
+ | Option | Description |
37
+ | ---------------- | ---------------------------------- |
38
+ | `--chain <name>` | Blockchain network (default: base) |
39
+ | `--json` | Output result as JSON |
40
+
41
+ ## Input Validation
42
+
43
+ Before constructing the command, validate all user-provided values to prevent shell injection:
44
+
45
+ - **amount**: Must match `^\$?[\d.]+$` (digits, optional decimal point, optional `$` prefix). Reject if it contains spaces, semicolons, pipes, backticks, or other shell metacharacters.
46
+ - **recipient**: Must be a valid `0x` hex address (`^0x[0-9a-fA-F]{40}$`) or an ENS name (`^[a-zA-Z0-9.-]+\.eth$`). Reject any value containing spaces or shell metacharacters.
47
+
48
+ Do not pass unvalidated user input into the command.
49
+
50
+ ## USDC Amounts
51
+
52
+ | Format | Example | Description |
53
+ | ------------- | ---------------------- | -------------------------------------- |
54
+ | Dollar prefix | `'$1.00'`, `'$0.50'` | USD notation (single-quote the `$`) |
55
+ | Decimal | `1.0`, `0.50` | Human-readable with decimal point |
56
+ | Whole number | `5`, `100` | Interpreted as whole USDC tokens |
57
+ | Atomic units | `500000` | Large integers treated as atomic units |
58
+
59
+ **IMPORTANT**: Always single-quote amounts that use `$` to prevent bash variable expansion (e.g. `'$1.00'` not `$1.00`).
60
+
61
+ ## ENS Resolution
62
+
63
+ ENS names are automatically resolved to addresses via Ethereum mainnet. The command will:
64
+ 1. Detect ENS names (any string containing `.eth`)
65
+ 2. Resolve the name to an address
66
+ 3. Display both the ENS name and resolved address in the output
67
+
68
+ ## Examples
69
+
70
+ ```bash
71
+ # Send $1.00 USDC to an address
72
+ npx agnic@latest send 1 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7
73
+
74
+ # Send $0.50 USDC to an ENS name
75
+ npx agnic@latest send 0.50 vitalik.eth
76
+
77
+ # Send with dollar sign prefix (note the single quotes)
78
+ npx agnic@latest send '$5.00' 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7
79
+
80
+ # Get JSON output
81
+ npx agnic@latest send 1 vitalik.eth --json
82
+ ```
83
+
84
+ ## Prerequisites
85
+
86
+ - Must be authenticated (`npx agnic@latest status` to check)
87
+ - Wallet must have sufficient USDC balance (`npx agnic@latest balance` to check)
88
+
89
+ ## Error Handling
90
+
91
+ Common errors:
92
+
93
+ - "Not authenticated" — Run `npx agnic@latest auth login` first
94
+ - "Insufficient balance" — Check balance with `npx agnic@latest balance`
95
+ - "Could not resolve ENS name" — Verify the ENS name exists
96
+ - "Invalid recipient" — Must be valid 0x address or ENS name
package/skills/trade-tokens/SKILL.md ADDED
@@ -0,0 +1,107 @@
1
+ ---
2
+ name: trade-tokens
3
+ description: Swap or trade tokens on Base network. Use when you or the user want to trade, swap, exchange, buy, sell, or convert between tokens like USDC, ETH, and WETH. Covers phrases like "buy ETH", "sell ETH for USDC", "convert USDC to ETH", "get some ETH", "swap tokens", "trade USDC for WETH".
4
+ user-invocable: true
5
+ disable-model-invocation: false
6
+ allowed-tools: ["Bash(npx agnic@latest status*)", "Bash(npx agnic@latest trade *)", "Bash(npx agnic@latest balance*)"]
7
+ ---
8
+
9
+ # Trading Tokens
10
+
11
+ Use the `npx agnic@latest trade` command to swap tokens on Base network. You must be authenticated to trade.
12
+
13
+ ## Confirm wallet is initialized and authed
14
+
15
+ ```bash
16
+ npx agnic@latest status
17
+ ```
18
+
19
+ If the wallet is not authenticated, refer to the `authenticate-wallet` skill.
20
+
21
+ ## Command Syntax
22
+
23
+ ```bash
24
+ npx agnic@latest trade <amount> <from> <to> [options]
25
+ ```
26
+
27
+ ## Arguments
28
+
29
+ | Argument | Description |
30
+ | -------- | ---------------------------------------------------------------------- |
31
+ | `amount` | Amount to swap (see Amount Formats below) |
32
+ | `from` | Source token: alias (usdc, eth, weth) or contract address (0x...) |
33
+ | `to` | Destination token: alias (usdc, eth, weth) or contract address (0x...) |
34
+
35
+ ## Amount Formats
36
+
37
+ | Format | Example | Description |
38
+ | ------------- | ---------------------- | -------------------------------------- |
39
+ | Dollar prefix | `'$1.00'`, `'$0.50'` | USD notation (decimals based on token) |
40
+ | Decimal | `1.0`, `0.50`, `0.001` | Human-readable with decimal point |
41
+ | Whole number | `5`, `100` | Interpreted as whole tokens |
42
+ | Atomic units | `500000` | Large integers treated as atomic units |
43
+
44
+ **Auto-detection**: Large integers without a decimal point are treated as atomic units. For example, `500000` for USDC (6 decimals) = $0.50.
45
+
46
+ **IMPORTANT**: Always single-quote amounts that use `$` to prevent bash variable expansion (e.g. `'$1.00'` not `$1.00`).
47
+
48
+ ## Token Aliases
49
+
50
+ | Alias | Token | Decimals | Address |
51
+ | ----- | ----- | -------- | ------------------------------------------ |
52
+ | usdc | USDC | 6 | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
53
+ | eth | ETH | 18 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
54
+ | weth | WETH | 18 | 0x4200000000000000000000000000000000000006 |
55
+
56
+ ## Options
57
+
58
+ | Option | Description |
59
+ | -------------------- | --------------------------------------------- |
60
+ | `-s, --slippage <n>` | Slippage tolerance in basis points (100 = 1%) |
61
+ | `--json` | Output result as JSON |
62
+
63
+ ## Input Validation
64
+
65
+ Before constructing the command, validate all user-provided values to prevent shell injection:
66
+
67
+ - **amount**: Must match `^\$?[\d.]+$` (digits, optional decimal point, optional `$` prefix). Reject if it contains spaces, semicolons, pipes, backticks, or other shell metacharacters.
68
+ - **from / to**: Must be a known alias (`usdc`, `eth`, `weth`) or a valid `0x` hex address (`^0x[0-9a-fA-F]{40}$`). Reject any other value.
69
+ - **slippage**: Must be a positive integer (`^\d+$`).
70
+
71
+ Do not pass unvalidated user input into the command.
72
+
73
+ ## Examples
74
+
75
+ ```bash
76
+ # Swap $1 USDC for ETH (dollar prefix — note the single quotes)
77
+ npx agnic@latest trade '$1' usdc eth
78
+
79
+ # Swap 0.50 USDC for ETH (decimal format)
80
+ npx agnic@latest trade 0.50 usdc eth
81
+
82
+ # Swap 0.01 ETH for USDC
83
+ npx agnic@latest trade 0.01 eth usdc
84
+
85
+ # Swap with custom slippage (2%)
86
+ npx agnic@latest trade '$5' usdc eth --slippage 200
87
+
88
+ # Get JSON output
89
+ npx agnic@latest trade '$1' usdc eth --json
90
+ ```
91
+
92
+ ## Prerequisites
93
+
94
+ - Must be authenticated (`npx agnic@latest status` to check)
95
+ - Wallet must have sufficient balance of the source token
96
+ - Trading is only available on Base mainnet
97
+
98
+ ## Error Handling
99
+
100
+ Common errors:
101
+
102
+ - "Not authenticated" — Run `npx agnic@latest auth login` first
103
+ - "Invalid token" — Use a valid alias (usdc, eth, weth) or 0x address
104
+ - "Cannot swap a token to itself" — From and to must be different
105
+ - "Swap failed: TRANSFER_FROM_FAILED" — Insufficient balance or approval issue
106
+ - "No liquidity" — Try a smaller amount or different token pair
107
+ - "Amount has X decimals but token only supports Y" — Too many decimal places
package/skills-lock.json ADDED
@@ -0,0 +1,45 @@
1
+ {
2
+ "version": 1,
3
+ "skills": {
4
+ "authenticate-wallet": {
5
+ "source": "/Users/asadsafari/Desktop/Projects/fitchecktest/agnicwallet-project/agnic-wallet-skills",
6
+ "sourceType": "local",
7
+ "computedHash": "74ef64363b7511197e6c1716fef89e4a1e81ba7f498056835fa901a9a2c01b99"
8
+ },
9
+ "check-balance": {
10
+ "source": "/Users/asadsafari/Desktop/Projects/fitchecktest/agnicwallet-project/agnic-wallet-skills",
11
+ "sourceType": "local",
12
+ "computedHash": "f10496084d9bf659e310136df35dbb387d6f217d54e58a45fca28d6a818223ff"
13
+ },
14
+ "fund-wallet": {
15
+ "source": "/Users/asadsafari/Desktop/Projects/fitchecktest/agnicwallet-project/agnic-wallet-skills",
16
+ "sourceType": "local",
17
+ "computedHash": "7aeb3e1cec7cba25583a0beefa8144dd7aebb300db52e5e41c4aa5ee844a509f"
18
+ },
19
+ "get-agent-identity": {
20
+ "source": "/Users/asadsafari/Desktop/Projects/fitchecktest/agnicwallet-project/agnic-wallet-skills",
21
+ "sourceType": "local",
22
+ "computedHash": "b71599479c6a337980b26a98bb99b3a2688d3ce2ae80472c9ca3827624031c7f"
23
+ },
24
+ "pay-for-service": {
25
+ "source": "/Users/asadsafari/Desktop/Projects/fitchecktest/agnicwallet-project/agnic-wallet-skills",
26
+ "sourceType": "local",
27
+ "computedHash": "bfbc7396f25604d9f6ad6f5075b27c9a285f9da145b66d2e916638bc9ad3c7c8"
28
+ },
29
+ "search-for-service": {
30
+ "source": "/Users/asadsafari/Desktop/Projects/fitchecktest/agnicwallet-project/agnic-wallet-skills",
31
+ "sourceType": "local",
32
+ "computedHash": "1e5f108a628b15184f5044af4d47cc63cff2362de3b98efa0785c9a23a18ece6"
33
+ },
34
+ "send-usdc": {
35
+ "source": "/Users/asadsafari/Desktop/Projects/fitchecktest/agnicwallet-project/agnic-wallet-skills",
36
+ "sourceType": "local",
37
+ "computedHash": "890ea005d0a629b093fe4be952169eac50de034d0fe1ba039518df5851cf26c8"
38
+ },
39
+ "trade-tokens": {
40
+ "source": "/Users/asadsafari/Desktop/Projects/fitchecktest/agnicwallet-project/agnic-wallet-skills",
41
+ "sourceType": "local",
42
+ "computedHash": "14743ac9f8f1410dab6f34b865fbedb0d1ee136bce329418945963140d671bfe"
43
+ }
44
+ }
45
+ }