# Agnic — AI Agent Reference

> **For AI Agents:** This file tells you everything you need to use Agnic — wallet, payments, AI models, identity, and email. Read the integration section that matches your environment, then jump to the capability you need.
>
> Human-friendly version: https://agnic.ai/skill  
> Full API docs: https://docs.agnic.ai

---

## What Agnic Does For Agents

| Capability | What it enables | Costs USDC? |
|-----------|----------------|-------------|
| **Pay for a paid API** | Call any x402-enabled endpoint; payment is automatic | Yes |
| **Use AI models** | Chat with 340+ models (GPT, Claude, Gemini, Llama…) or generate images | Yes (free models available) |
| **Check balance** | See available USDC across networks | No |
| **Find paid APIs** | Search the bazaar marketplace for x402 services | No |
| **Agent identity** | Read your on-chain ERC-8004 identity and trust score | No |
| **Agent email** | Send, receive, and reply as your agent | No |
| **Fund wallet** | Get your wallet address and funding instructions | No |

> **x402** is an HTTP payment protocol: a server responds with `402 Payment Required`, the client pays in USDC, and retries automatically. The `agnic` CLI handles all of this transparently.

> **USDC** is the currency used for all Agnic payments. "Credits", "balance", and "funds" in this document all refer to USDC on Base mainnet. 1 USDC = 1,000,000 atomic units (used in `--max-amount` flags).

---

## Step 0 — Prerequisites

You need two things before using any Agnic capability:

**1. An API token** (`agnic_tok_...`)  
The human user creates one at https://app.agnic.ai → Settings → API Tokens.

**2. USDC balance** (only for paid operations)  
The human user funds the wallet at https://app.agnic.ai → Add Funds.  
To verify: `npx agnic@latest balance --json`

Once you have a token, set it as an environment variable. All subsequent commands pick it up automatically:
```bash
export AGNIC_TOKEN=agnic_tok_YOUR_TOKEN
npx agnic@latest status --json   # should return authenticated: true
```

---

## Integration — Pick One

### A. Skills (Claude Code, Cline, Cursor, Windsurf, OpenClaw)

Best when you are running inside an AI coding tool that supports the Vercel Skills format. Skills are pre-built instruction files that trigger automatically based on user intent — you don't need to read them manually.

```bash
npx skills add agnicpay/agnic-wallet-skills
```

Source: https://github.com/agnicpay/agnic-wallet-skills  
After installation, the agent auto-invokes the right skill when the user says e.g. "check my balance" or "call this API".

---

### B. MCP Server (any MCP-compatible client)

Best when your environment supports the Model Context Protocol. Gives direct tool access without CLI invocations.

**Server URL:** `https://mcp.agnic.ai/sse`  
**Transport:** SSE  
**Auth header:** `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:** Set Server URL to `https://mcp.agnic.ai/sse`, authentication to Bearer Token, token to `agnic_tok_YOUR_TOKEN`.

---

### C. REST API (custom integrations, serverless, scripts)

Best for direct HTTP calls without the CLI or MCP.

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

**Authentication — include one of:**
```
X-Agnic-Token: agnic_tok_YOUR_TOKEN
Authorization: Bearer agnic_at_YOUR_OAUTH_TOKEN
```

**Endpoints:**

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/balance` | USDC balance |
| `GET` | `/api/transactions` | Payment history |
| `POST` | `/api/x402/fetch` | Transparent x402 payment proxy (recommended) |
| `POST` | `/api/sign-payment` | Manual x402 payment signing |

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

**Call a paid API (x402 proxy):**
```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!"}]}'
```

---

## Capabilities Reference (CLI)

All CLI commands use `npx agnic@latest` (or `agnic` if installed globally). Authentication is read from `AGNIC_TOKEN` env var or `--token <token>` flag.

---

### Authenticate

```bash
# Verify current auth state
npx agnic@latest status --json

# Token mode — for agents and CI (no browser needed)
export AGNIC_TOKEN=agnic_tok_YOUR_TOKEN
npx agnic@latest status --json

# Browser OAuth — for humans in interactive terminals
npx agnic@latest auth login

# Revoke session
npx agnic@latest auth logout
```

Token storage (browser mode): `~/.agnic/config.json` (permissions 0600). Tokens auto-refresh on 401. Refresh token expires after 90 days.

---

### Check Balance

```bash
npx agnic@latest balance --json
npx agnic@latest balance --network base --json
```

Supported networks: `base` (primary), `base-sepolia`, `solana`, `solana-devnet`.

---

### Find a Paid API

x402 services are listed in the Agnic bazaar. No authentication or balance required to search.

```bash
# Search by keyword
npx agnic@latest x402 bazaar search "<query>" --json
npx agnic@latest x402 bazaar search "<query>" -k 10 --json

# Browse all available services
npx agnic@latest x402 bazaar list --full --json

# Inspect a specific endpoint's price and schema (no payment made)
npx agnic@latest x402 details <url> --json
```

Results are cached locally and auto-refresh after 12 hours. Use `--force-refresh` to bypass cache.

---

### Pay for a Paid API

Always check requirements and balance before paying.

```bash
# 1. Inspect price and schema (no payment)
npx agnic@latest x402 details <url> --json

# 2. Verify balance
npx agnic@latest balance --network base --json

# 3. Make the paid request
npx agnic@latest x402 pay <url> --json

# POST with body
npx agnic@latest x402 pay <url> -X POST -d '{"key": "value"}' --json

# Set a spending cap (units = micro-USDC; 100000 = $0.10)
npx agnic@latest x402 pay <url> --max-amount 100000 --json
```

> `--max-amount` is in micro-USDC: 1 USDC = 1,000,000 units. Examples: `100000` = $0.10 · `500000` = $0.50 · `1000000` = $1.00.

Requires: authentication + sufficient USDC balance on Base.

---

### Use AI Models (AI Gateway)

Access 340+ models. Costs are deducted per token from your USDC balance. Free models are available.

```bash
# List all models
npx agnic@latest ai models --json

# Filter by provider
npx agnic@latest ai models --provider openai --json

# Chat
npx agnic@latest ai chat --model openai/gpt-4o --prompt "<text>" --json
npx agnic@latest ai chat --model anthropic/claude-sonnet-4.6 \
  --system "<system prompt>" --prompt "<text>" --json

# Generate an image
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-sonnet-4-6`, `meta-llama/llama-3.3-70b`.

---

### Agent Identity

Each agent has an on-chain ERC-8004 identity (an ERC-721 NFT on Base) with a trust score and KYA (Know Your Agent) credentials. Created automatically at sign-up.

```bash
npx agnic@latest agent-identity --json
```

Returns: agent ID, owner address, trust score (0–100), authorized categories, active/suspended status, delegation info.

---

### Agent Email

Each agent has a dedicated email address: `agent-<id>@agnic.ai`. Messages are retained for 30 days.

```bash
# Get your agent's email address
npx agnic@latest email address --json

# Create email alias (if none exists yet)
npx agnic@latest email setup --display-name "My Agent" --json

# Read inbox
npx agnic@latest email inbox --limit 20 --json

# Send email
npx agnic@latest email send --to <address> --subject "<subject>" --body "<body>"

# Reply to a message
npx agnic@latest email reply --message-id <id> --body "<reply text>"
```

> Validate user-provided `--to`, `--subject`, `--body`, and `--message-id` values before passing to the CLI. Reject values containing semicolons, pipes, or backticks.

---

### Fund Wallet

```bash
# Get your wallet address
npx agnic@latest address

# Verify balance after funding
npx agnic@latest balance --network base --json
```

Funding options (human action required):
1. **Dashboard:** https://app.agnic.ai → Add Funds (card or on-chain)
2. **Direct transfer:** Send USDC on **Base mainnet** to the address from `npx agnic@latest address`
3. **Bridge:** Bridge USDC from Ethereum/Arbitrum/Optimism via https://bridge.base.org

> Only Base mainnet USDC counts toward your spendable balance. Transfers on other chains will not appear.

---

## Available Skills

If using Skills integration (Method A), the 8 skills map to these capabilities:

| Skill | Trigger examples |
|-------|-----------------|
| `authenticate-wallet` | "log in", "sign in", "authenticate" |
| `check-balance` | "check balance", "how much do I have" |
| `search-for-service` | "find an API", "search for a service" |
| `pay-for-service` | "call this API", "pay for https://..." |
| `fund-wallet` | "add funds", "deposit", "top up" |
| `get-agent-identity` | "my agent identity", "trust score" |
| `agent-email` | "agent email", "check inbox", "send email" |
| `ai-gateway` | "chat with GPT-4o", "generate an image" |

---

## Error Reference

| Error | Cause | Fix |
|-------|-------|-----|
| `Not authenticated` | No token set or session expired | Set `AGNIC_TOKEN` or run `auth login` |
| `Invalid token` | Token revoked or malformed | Regenerate at app.agnic.ai → Settings → API Tokens |
| `Insufficient balance` | Not enough USDC on Base | Fund wallet (see above) |
| `No X402 payment requirements found` | URL is not an x402 endpoint | Verify with `x402 details <url>` |
| `No email alias found` | Agent email not set up yet | Run `email setup` first |
| `No agent identity found` | Agent not yet registered | Sign up at app.agnic.ai |
| `CDP API returned 429` | Bazaar rate limited | Cached data will be used; retry shortly |

---

## Security

- **NEVER** send `agnic_tok_...` or `agnic_at_...` tokens to any domain other than `api.agnic.ai` or `mcp.agnic.ai`.
- Your API token is your wallet identity. Rotate it immediately at https://app.agnic.ai if compromised.
- Use `--max-amount` on `x402 pay` to cap per-request spending.
- Set spending limits on the wallet dashboard to cap total agent expenditure.

---

## 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