# Agnic Skill Guide

> **For AI Agents:** Read this file to discover, install, and use Agnic services — wallets, payments, identity, AI gateway, and more.
>
> Human-friendly version: https://agnic.ai/skill
> Full API docs: https://docs.agnic.ai/docs/agnicpay-features

---

## What is Agnic?

Agnic is the financial infrastructure layer for AI agents. It provides:

- **AgnicPay** — Autonomous wallets for AI agents. Fund with USDC, pay only for what you use. Access 340+ AI models. Make x402 payments. Send and trade tokens. (`pay.agnic.ai`)
- **AgnicHub** — x402 marketplace. Discover and call paid APIs with cryptographic proof. (`agnichub.xyz`)
- **Agnic.ID** — Identity layer. W3C DIDs and Verifiable Credentials for agents and humans. KYA (Know Your Agent) enforcement. (`agnic.id`)
- **Agnic Monetization** — Let your users access 340+ AI models pay-per-request. You earn a margin on every call. (`agnic.ai/showcase`)

---

## Quick Start — First-Time Wallet Setup

Follow these steps to initialize an Agnic wallet and get an API key:

### Step 1: Check auth status
```bash
npx agnic@latest status
```

### Step 2: Authenticate (email OTP)
```bash
npx agnic@latest auth login your@email.com
# Check your email for a 6-digit OTP code
npx agnic@latest auth verify <flowId> <otp>
```

### Step 3: Confirm authentication
```bash
npx agnic@latest status --json
```

### Step 4: Fund your wallet
```bash
npx agnic@latest address        # shows your wallet address
npx agnic@latest balance --json # check current balance
```
Send USDC to your wallet address on Base or Solana, or fund via the dashboard at https://pay.agnic.ai

### Step 5: Get your API token
Visit https://pay.agnic.ai to get your API token from the dashboard.
Your token will have the format: `agnic_tok_YOUR_TOKEN`

---

## Install Agnic Skills

Agnic publishes a set of Vercel AI Skills for Claude Code, Claude Cowork, OpenClaw, and any other agent that supports the [Vercel Skills format](https://github.com/vercel/skills).

### Install via CLI
```bash
npx skills add agnicpay/agnic-wallet-skills
```

### Skills Repository
https://github.com/agnicpay/agnic-wallet-skills

---

## Available Skills (10)

Once installed, the agent will automatically invoke the right skill based on user intent.

| Skill | Description | Example Triggers |
|-------|-------------|-----------------|
| `authenticate-wallet` | Sign in to AgnicPay via email OTP | "log in", "sign in", "authenticate" |
| `check-balance` | Check USDC balance across networks (Base, Solana) | "what's my balance", "how much do I have" |
| `send-usdc` | Send USDC to an Ethereum or Solana address | "send 10 USDC to 0x...", "transfer funds" |
| `trade-tokens` | Swap tokens on Base (USDC, ETH, WETH, cbETH, DAI, AERO) | "swap ETH for USDC", "trade tokens" |
| `search-for-service` | Discover x402-enabled paid APIs | "find a sentiment API", "search for APIs" |
| `pay-for-service` | Make a paid API request via x402 | "call this API", "pay for https://..." |
| `fund-wallet` | Get funding instructions | "add funds", "deposit USDC", "top up" |
| `get-agent-identity` | Check on-chain ERC-8004 identity and trust score | "my identity", "trust score", "KYA" |
| `agent-email` | Manage agent email — send, receive, inbox | "send an email", "check inbox", "email setup" |
| `ai-gateway` | Access 340+ AI models — chat and image generation | "chat with GPT-4o", "generate an image", "list AI models" |

### Skill: authenticate-wallet
```bash
npx agnic@latest status                      # check auth state
npx agnic@latest auth login <email>          # send OTP
npx agnic@latest auth verify <flowId> <otp>  # verify OTP
```

### Skill: check-balance
```bash
npx agnic@latest balance --json
npx agnic@latest balance --network base --json
npx agnic@latest balance --network solana --json
```
Supported networks: `base`, `solana`, `base-sepolia`, `solana-devnet`

### Skill: send-usdc
```bash
npx agnic@latest balance --network base --json
npx agnic@latest send <amount> <address> --json
npx agnic@latest send <amount> <address> --network solana --memo "payment" --json
```

### Skill: trade-tokens
```bash
npx agnic@latest balance --network base --json
npx agnic@latest trade <amount> <sellToken> <buyToken> --dry-run --json  # preview
npx agnic@latest trade <amount> <sellToken> <buyToken> --json             # execute
```
Supported tokens: `USDC`, `ETH`, `WETH`, `cbETH`, `DAI`, `AERO`
Optional: `--slippage <percent>` (default: 1.0)

### Skill: search-for-service
```bash
npx agnic@latest x402 search "<query>" --json
npx agnic@latest x402 search "<query>" --category AI --json
```
Categories: `AI`, `Crypto`, `Data`, `Trading`, `Finance`, `Weather`

### Skill: pay-for-service
```bash
npx agnic@latest balance --network base --json
npx agnic@latest x402 pay <url> --method GET --json
npx agnic@latest x402 pay <url> --method POST --body '{"key":"value"}' --json
```

### Skill: fund-wallet
```bash
npx agnic@latest address         # get wallet address
npx agnic@latest balance --json  # verify after funding
```
Fund via dashboard: https://pay.agnic.ai

### Skill: get-agent-identity
```bash
npx agnic@latest status --json   # shows wallet address and identity
npx agnic@latest address
```
Identity management: https://pay.agnic.ai

### Skill: agent-email
```bash
npx agnic@latest email address          # check email (e.g. agent-123@agnic.ai)
npx agnic@latest email setup            # create email if none exists
npx agnic@latest email inbox --limit 20 --json
npx agnic@latest email send --to <address> --subject "<subject>" --body "<body>"
npx agnic@latest email reply --message-id <id> --body "<reply>"
```
Emails are retained for 30 days.

### Skill: ai-gateway
```bash
npx agnic@latest ai models --json
npx agnic@latest ai models --provider openai --json
npx agnic@latest ai chat --model openai/gpt-4o --prompt "<text>" --json
npx agnic@latest ai chat --model anthropic/claude-3.5-sonnet --system "<system>" --prompt "<text>" --json
npx agnic@latest ai image --prompt "<text>" --output image.png
npx agnic@latest ai image --prompt "<text>" --aspect-ratio 16:9 --output wide.png
```
Model format: `provider/model-name` (e.g., `openai/gpt-4o`, `anthropic/claude-3.5-sonnet`, `meta-llama/llama-3.3-70b`)
Free models: `meta-llama/*`, `google/gemma-*`, `mistralai/*`

---

## MCP Server Integration

Connect to the AgnicPay MCP server to give your AI client direct access to wallet tools.

**Server URL:** `https://mcp.agnic.ai/sse`
**Authentication:** `Bearer <your-api-token>`

### Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "agnicpay": {
      "url": "https://mcp.agnic.ai/sse",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer agnic_tok_YOUR_TOKEN"
      }
    }
  }
}
```

### Claude Code (CLI)
```bash
claude mcp add agnicpay --transport sse --url https://mcp.agnic.ai/sse \
  --header "Authorization: Bearer agnic_tok_YOUR_TOKEN"
```

### OpenClaw
Add an MCP server with:
- URL: `https://mcp.agnic.ai/sse`
- Transport: SSE
- Header: `Authorization: Bearer agnic_tok_YOUR_TOKEN`

Or install skills directly:
```bash
npx skills add agnicpay/agnic-wallet-skills
```

### n8n
In your n8n MCP node, configure:
- **Server URL:** `https://mcp.agnic.ai/sse`
- **Authentication:** Bearer Token
- **Token:** `agnic_tok_YOUR_TOKEN`

---

## REST API Reference

**Base URL:** `https://api.agnic.ai`

### Authentication

```
# API Token
X-Agnic-Token: agnic_tok_YOUR_TOKEN

# OAuth2 Bearer
Authorization: Bearer agnic_at_YOUR_OAUTH_TOKEN
```

### Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/balance` | Check USDC wallet balance |
| `GET` | `/api/transactions` | View payment history |
| `POST` | `/api/x402/fetch` | Transparent x402 payment proxy (recommended) |
| `POST` | `/api/sign-payment` | Manual x402 payment signing |
| `POST` | `/api/trade` | Token swaps on Base via DEX aggregation |

### GET /api/balance
```bash
curl https://api.agnic.ai/api/balance \
  -H "X-Agnic-Token: agnic_tok_YOUR_TOKEN"
```

### GET /api/transactions
```bash
curl https://api.agnic.ai/api/transactions \
  -H "X-Agnic-Token: agnic_tok_YOUR_TOKEN"
```

### POST /api/x402/fetch (recommended)
Transparently handles x402 payment negotiation — use this instead of making raw requests to paid APIs.
```bash
curl -X POST https://api.agnic.ai/api/x402/fetch \
  -H "X-Agnic-Token: agnic_tok_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/data",
    "method": "GET"
  }'
```

### POST /api/sign-payment
For manual x402 flow where you handle the 402 response yourself.
```bash
curl -X POST https://api.agnic.ai/api/sign-payment \
  -H "X-Agnic-Token: agnic_tok_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentRequirements": { ... }
  }'
```

### POST /api/trade
```bash
curl -X POST https://api.agnic.ai/api/trade \
  -H "X-Agnic-Token: agnic_tok_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sellToken": "USDC",
    "buyToken": "ETH",
    "sellAmount": "10"
  }'
```

### AI Gateway (OpenAI-compatible)
```bash
curl https://api.agnic.ai/v1/chat/completions \
  -H "Authorization: Bearer agnic_tok_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

---

## OAuth2 Flow

For agents acting on behalf of users, use OAuth2:

### Authorization URL
```
https://pay.agnic.ai/oauth-consent?
  client_id=your-app-name
  &redirect_uri=https://yourapp.com/callback
  &state=random_csrf_token
  &scope=payments:sign+balance:read
```

### Token Exchange
```bash
curl -X POST https://api.agnic.ai/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "abc123",
    "redirect_uri": "https://yourapp.com/callback",
    "client_id": "your-app-name"
  }'
```
Returns: `agnic_at_...` (access token) and `agnic_rt_...` (refresh token)

---

## Agent-Specific Setup

### Claude Code
```bash
# Install skills
npx skills add agnicpay/agnic-wallet-skills

# Or add MCP server
claude mcp add agnicpay --transport sse --url https://mcp.agnic.ai/sse \
  --header "Authorization: Bearer agnic_tok_YOUR_TOKEN"
```

### Claude Cowork
- Install skills via: `npx skills add agnicpay/agnic-wallet-skills`
- Or configure the MCP server in your Cowork session settings

### OpenClaw
- Install skills: `npx skills add agnicpay/agnic-wallet-skills`
- Or add the MCP server: URL `https://mcp.agnic.ai/sse`, Bearer auth

### Generic MCP Client
- Transport: SSE
- URL: `https://mcp.agnic.ai/sse`
- Header: `Authorization: Bearer agnic_tok_YOUR_TOKEN`

---

## Security

- **NEVER** send your API token (`agnic_tok_...`) or OAuth token (`agnic_at_...`) to any domain other than `api.agnic.ai` or `mcp.agnic.ai`.
- Your API token represents your wallet identity.
- If compromised, rotate your token immediately at https://pay.agnic.ai.
- Set spending limits on your wallet to cap agent expenditure.

---

## Support & Resources

- Dashboard: https://pay.agnic.ai
- API Docs: https://docs.agnic.ai/docs/agnicpay-features
- Skills Repo: https://github.com/agnicpay/agnic-wallet-skills
- Human guide: https://agnic.ai/skill
- Support: support@agnic.ai