# Agnic Skill Guide

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

---

## What is Agnic?

Agnic is the cockpit for autonomous AI agents. One dashboard at `app.agnic.ai` provides:

- **AI Gateway** — Access 340+ AI models (OpenAI, Anthropic, Gemini, Llama, and more) with a single API key. Pay-per-token, no subscriptions. (`app.agnic.ai/gateway`)
- **Agent Identity** — W3C DID:WEB standard. Verifiable credentials (SD-JWT). Agent email at `agnic.id`. (`agnic.id`)
- **Service Discovery** — Discover and call x402-enabled paid APIs from the bazaar marketplace. (`app.agnic.ai/discover`)
- **API Monetization** — Register your API and earn per request. Agents discover you via MCP. (`app.agnic.ai/monetize`)

---

## Quick Start — First-Time Setup

### Step 1: Install the CLI
```bash
npm install -g agnic
```

### Step 2: Authenticate

**Token mode (recommended for agents):**
```bash
# Pass token directly
npx agnic@latest --token <agnic_token> status

# Or set as environment variable
export AGNIC_TOKEN=<agnic_token>
npx agnic@latest status
```

**Browser OAuth (for humans):**
```bash
npx agnic@latest auth login
# CLI opens browser → sign in → tokens stored in ~/.agnic/config.json
```

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

### Step 4: Add credits
Visit https://app.agnic.ai → "Add Funds" to top up your wallet with platform credits.

```bash
npx agnic@latest balance --json  # verify credit balance
```

### Step 5: Get your API token
Visit https://app.agnic.ai to copy your API token (`agnic_tok_...`)

---

## Install Agnic Skills

Agnic publishes pre-built skills for Claude Code, OpenClaw, and any agent supporting the [Vercel Skills format](https://github.com/vercel/skills).

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

### Clone locally
```bash
git clone https://github.com/agnicpay/agnic-wallet-skills
npx skills add ./agnic-wallet-skills
```

---

## Available Skills (8)

| Skill | Trigger Phrases | Description |
|-------|-----------------|-------------|
| `authenticate` | "log in", "sign in", "authenticate" | Browser OAuth or token-based headless auth |
| `check-balance` | "check balance", "how much do I have" | Credit balance across supported networks |
| `search-for-service` | "find an API", "search for" | Discover x402-enabled APIs in the bazaar |
| `pay-for-service` | "call this API", "use this service" | Make x402 paid API requests |
| `fund-wallet` | "add funds", "deposit", "top up" | Instructions for adding credits |
| `get-agent-identity` | "agent identity", "trust score" | On-chain ERC-8004 identity and verifiable credentials |
| `agent-email` | "agent email", "check inbox", "send email" | Send, receive, and manage agent email |
| `ai-gateway` | "chat with GPT-4o", "generate an image" | Access 340+ AI models |

### Skill: authenticate
```bash
# Check auth state
npx agnic@latest status

# Token mode (agents)
npx agnic@latest --token <agnic_token> status
export AGNIC_TOKEN=<agnic_token>

# Browser OAuth (humans)
npx agnic@latest auth login

# Logout
npx agnic@latest auth logout
```
Token storage: `~/.agnic/config.json` (0600). Auto-refresh on 401; refresh token expires after 90 days.

### Skill: check-balance
```bash
npx agnic@latest balance
npx agnic@latest balance --json
```

### Skill: search-for-service
```bash
# Search the bazaar
npx agnic@latest x402 bazaar search "<query>" --json
npx agnic@latest x402 bazaar search "<query>" -k 10 --json

# List all bazaar resources
npx agnic@latest x402 bazaar list --json
npx agnic@latest x402 bazaar list --full --json

# Inspect x402 requirements for a specific URL
npx agnic@latest x402 details <url> --json
```
Results are cached locally and auto-refresh after 12 hours. Use `--force-refresh` to force re-fetch.

### Skill: pay-for-service
```bash
# Recommended workflow:
npx agnic@latest x402 details <url>   # 1. inspect requirements
npx agnic@latest balance --json       # 2. verify credits
npx agnic@latest x402 pay <url> --json  # 3. make request

# GET request
npx agnic@latest x402 pay https://example.com/api/weather --json

# POST request with body
npx agnic@latest x402 pay https://example.com/api/sentiment \
  -X POST -d '{"text": "I love this product"}' --json

# With spending cap
npx agnic@latest x402 pay <url> --max-amount 100000 --json
```

### Skill: fund-wallet
```bash
npx agnic@latest address         # get wallet address
npx agnic@latest balance --json  # verify credits after funding
```
Add credits at: https://app.agnic.ai → "Add Funds" (card or direct transfer)

### Skill: get-agent-identity
```bash
npx agnic@latest agent-identity --json
```
Returns: agent ID (ERC-721 on ERC-8004 Identity Registry), owner address, trust score (0–100), categories, status, delegation.

### Skill: agent-email
```bash
npx agnic@latest email address                           # get agent email address
npx agnic@latest email setup [--display-name <name>]    # create if none exists
npx agnic@latest email inbox [--limit 20] --json
npx agnic@latest email send --to <addr> --subject "<subject>" --body "<body>"
npx agnic@latest email reply --message-id <id> --body "<reply>"
```
Agent email format: `agent-{id}@agent.agnic.ai`. Messages retained 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`

---

## MCP Server Integration

Connect to the Agnic MCP server for direct tool access in any MCP-compatible client.

**Server URL:** `https://mcp.agnic.ai/sse`
**Transport:** SSE
**Auth:** `Authorization: Bearer agnic_tok_YOUR_TOKEN`

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

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

### n8n
In your n8n MCP node:
- **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` | Wallet credit balance |
| `GET` | `/api/transactions` | Payment history |
| `POST` | `/api/x402/fetch` | Transparent x402 payment proxy (recommended) |
| `POST` | `/api/sign-payment` | Manual x402 payment signing |

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

### POST /api/x402/fetch (recommended)
Transparently handles x402 payment negotiation.
```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"}'
```

### 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!"}]}'
```

---

## 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 it immediately at https://app.agnic.ai.
- Set spending limits on your wallet to cap agent expenditure.

---

## Support & Resources

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