---
name: icon-generator
description: Generate AI icons using the icon.new API. Use when the user wants to create icons, generate icon assets, or needs visual icons for their project.
---

# Icon Generator

Generate icons via the icon.new API. Supports credit-based and x402 crypto payment.

## API Endpoint

`POST https://icon.new/api/v1/generate`

## Authentication

Either:
1. **API Key**: `Authorization: Bearer $ICON_NEW_API_KEY` (get from https://icon.new/dashboard)
2. **x402 Payment** (v2): No key needed. $0.35 USDC per base icon, $0.50 USDC per premium icon (`colorful`, `animated`). Settled on Base mainnet.

## Request

```json
{
  "prompt": "string (required, max 100 chars)",
  "style": "outline | solid | simple | colorful | animated",
  "count": 1
}
```

| Parameter | Required | Description |
|-----------|----------|-------------|
| `prompt` | Yes | Icon description, max 100 characters |
| `style` | No | `outline` (default), `solid`, `simple`, `colorful`, or `animated` |
| `count` | No | Number of icons: 1-4 (default: 1) |

### Styles & x402 Pricing

| Style | Tier | Credits | x402 price |
|-------|------|---------|------------|
| `outline` | Base | 1 | $0.35 USDC |
| `solid` | Base | 1 | $0.35 USDC |
| `simple` | Base | 1 | $0.35 USDC |
| `colorful` | Premium | 3 | $0.50 USDC |
| `animated` | Premium | 3 | $0.50 USDC |

## Response

```json
{
  "icons": [
    {
      "id": "uuid",
      "url": "https://icon.new/api/v1/icons/uuid",
      "prompt": "rocket launching into space"
    }
  ],
  "credits": { "used": 1, "remaining": 42 },
  "payment": { "method": "credits" }
}
```

## Generate Icons

```bash
curl -s -X POST https://icon.new/api/v1/generate \
  -H "Authorization: Bearer $ICON_NEW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "rocket launching into space", "style": "outline"}'
```

Multiple variations:
```bash
curl -s -X POST https://icon.new/api/v1/generate \
  -H "Authorization: Bearer $ICON_NEW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "shopping cart", "style": "solid", "count": 3}'
```

## Download Icons

Append the format extension to the icon URL:

```bash
curl -s "https://icon.new/api/v1/icons/ICON_ID.svg" -o icon.svg
curl -s "https://icon.new/api/v1/icons/ICON_ID.png" -o icon.png
curl -s "https://icon.new/api/v1/icons/ICON_ID.ico" -o favicon.ico
```

Supported formats: `.svg`, `.png`, `.ico`

## x402 Payment (No API Key)

The server speaks **x402 v2**. Send a request without an Authorization header and you'll get a `402 Payment Required`:

```bash
curl -i -X POST https://icon.new/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "rocket launching into space", "style": "colorful"}'
```

The payment requirements are returned in a base64-encoded `PAYMENT-REQUIRED` response header (not the body). Decoded, it matches the x402 v2 `PaymentRequired` shape:

```json
{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "https://icon.new/api/v1/generate",
    "description": "Generate 1 colorful icon ($0.50 each)",
    "mimeType": "application/json"
  },
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "500000",
    "payTo": "0x…",
    "maxTimeoutSeconds": 60,
    "extra": { "name": "USD Coin", "version": "2" }
  }]
}
```

- `network` is CAIP-2 (`eip155:8453` = Base mainnet).
- `amount` is in USDC atomic units (6 decimals). `$0.35` → `"350000"`, `$0.50` → `"500000"`.
- `asset` is the USDC contract on Base mainnet.

Sign an EIP-3009 authorization with an x402 v2 client (e.g. `@x402/core`, awal) and retry with a base64-encoded `PAYMENT-SIGNATURE` header. On success the server returns the icons (200) plus a base64-encoded `PAYMENT-RESPONSE` header carrying the on-chain settlement. Total cost = per-style price × `count`. Learn more: https://x402.org

## Pricing (Credits)

| Pack | Price | Credits |
|------|-------|---------|
| Free | $0 | 3 credits |
| Espresso | $5 | 15 credits |
| Latte | $15 | 50 credits |
| Nitro | $30 | 100 credits |

Base icons (`outline`, `solid`, `simple`) cost 1 credit each; premium icons (`colorful`, `animated`) cost 3 credits each. Credits never expire. Buy at https://icon.new/pricing

## Errors

| Status | Meaning |
|--------|---------|
| 400 | Invalid request (prompt too long, etc.) |
| 401 | Invalid or missing API key |
| 402 | Insufficient credits (pay with x402 or buy credits) |
| 500 | Server error |

## Setup

The user needs either:
1. An API key from https://icon.new/dashboard set as `ICON_NEW_API_KEY`
2. An x402-compatible wallet for pay-per-request

If no API key is set, remind the user to configure it or mention x402.

## Best Practices

- Use `count` to batch multiple icons in one request instead of separate calls
- Check `credits.remaining` in the response before making more requests
- After generating, download icons and tell the user where files were saved
- SVG is best for web; ICO for favicons; PNG for general use