> ## Documentation Index
> Fetch the complete documentation index at: https://docs.limitguard.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys, x402 USDC micropayments, and sandbox mode

Limitguard supports two authentication modes: **API key** (prepaid balance) and **x402 USDC micropayments** (pay-per-use). [Sandbox mode](https://docs.limitguard.ai/sandbox.md) is available for testing without either.

## API Key Authentication

Pass your API key in the `X-API-Key` header:

```bash curl theme={null}
curl -X POST https://api.limitguard.ai/v1/entity/check \
  -H "X-API-Key: lg_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"entity_name": "Acme Corp BV", "country": "NL"}'
```

```python Python theme={null}
import httpx

response = httpx.post(
    "https://api.limitguard.ai/v1/entity/check",
    headers={"X-API-Key": "lg_live_xxxxxxxxxxxxxxxxxxxx"},
    json={"entity_name": "Acme Corp BV", "country": "NL"},
)
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.limitguard.ai/v1/entity/check", {
  method: "POST",
  headers: {
    "X-API-Key": "lg_live_xxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ entity_name: "Acme Corp BV", country: "NL" }),
});
```

A paid-tier API key skips the per-call x402 payment: each call is debited at list price from the key's prepaid balance instead. A free key still pays per call. The tier only selects the key's rate limits and its monthly cap (see [Rate Limits](https://docs.limitguard.ai/guides/rate-limits.md)).

### Key Format

| Prefix | Type | Use |
| - | - | - |
| `lg_live_` | Production key | Live data, real sources |
| `lg_sandbox_` | Sandbox key (`"tier": "sandbox"` on `POST /v1/keys/create`) | Mock data on the endpoints the sandbox covers, 10 requests per minute per IP; other priced endpoints charge it like a free key |

### Creating Keys

```bash curl theme={null}
curl -X POST https://api.limitguard.ai/v1/keys/create \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "tier": "free"}'
```

```python Python theme={null}
response = httpx.post(
    "https://api.limitguard.ai/v1/keys/create",
    json={"email": "you@example.com", "tier": "free"},
)
print(response.json()["api_key"])
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.limitguard.ai/v1/keys/create", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "you@example.com", tier: "free" }),
});
const { api_key } = await response.json();
```

`POST /v1/keys/create` can only provision `free` or `sandbox` tiers directly. To move up the ladder, create a free key first, then pay via `POST /v1/keys/upgrade/{tier}` (x402 required even if you already hold a key: see [Pricing](https://docs.limitguard.ai/pricing.md#api-key-tier-upgrades)):

| Tier | Top-up (credited to the prepaid balance) | Rate limits and monthly cap |
| - | - | - |
| `free` / `sandbox` | No prepaid top-up; 500 calls / 24 h is a ceiling, not an allowance: REST calls are still paid per call over x402 | 10 / min, 500 / 24 h, 500 / month |
| `indie` | \$29 | 30 / min, 1,000 / 24 h, 1,000 / month |
| `starter` | \$99 | 60 / min, 10,000 / 24 h, 10,000 / month |
| `growth` | \$299 | 120 / min, 50,000 / 24 h, 50,000 / month |
| `pro` | \$999 | 300 / min, 250,000 / 24 h, 250,000 / month |

A top-up buys balance, not a number of calls: each call is debited at its list price. Check the balance with `GET /v1/keys/usage`. The monthly cap counts calls, resets at 00:00 UTC on the 1st, and answers 429 with `Retry-After` when reached (see [Rate Limits](https://docs.limitguard.ai/guides/rate-limits.md#monthly-cap-per-key)).

> [!WARNING]
>
> The plaintext key is returned **once only**: store it securely. It is never stored server-side.

## x402 USDC Micropayments

For AI agents and pay-per-use access without a subscription. Send the base64-encoded JSON payment object in the `PAYMENT-SIGNATURE` header (x402 V2); the V1 `X-PAYMENT` header is still accepted.

> [!TIP]
>
> See the full [x402 Protocol](https://docs.limitguard.ai/x402-protocol.md) guide for step-by-step implementation with code examples.

### x402 V2 Flow

**1. Request without payment**

Make your API request normally. You'll receive HTTP 402 with payment requirements.

**2. Build payment signature**

Construct an EIP-3009 `TransferWithAuthorization` signature using the payment details from the 402 response: `network`, `asset`, `amount` and `payTo` of the `accepts` entry you pay.

**3. Retry with payment**

Retry the same request with the `PAYMENT-SIGNATURE` header (or the V1 `X-PAYMENT` header) containing the base64-encoded payment object.

### HTTP 402 Response

When you make a request without payment, the API returns the payment requirements (trimmed: the live body lists Base, Solana and a `settled-transfer` option, and recovery hints under `extensions`):

```json theme={null}
{
  "x402Version": 2,
  "error": "Payment Required",
  "errorCode": "payment_required",
  "resource": {
    "url": "https://api.limitguard.ai/v1/entity/check",
    "description": "Full entity trust check across multiple verification layers...",
    "mimeType": "application/json",
    "serviceName": "Limitguard",
    "tags": ["kyb", "sanctions", "lead-verification", "wallet-screening", "compliance"],
    "iconUrl": "https://limitguard.ai/icon-512.png"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "290000",
      "maxAmountRequired": "290000",
      "payTo": "0xFacilitatorAddress",
      "maxTimeoutSeconds": 600,
      "extra": {"name": "USD Coin", "version": "2", "decimals": 6}
    }
  ]
}
```

`amount` is in USDC 6-decimal units: `290000` is the x402 agent price of the `fresh` tier of `POST /v1/entity/check` today; an API key is debited the account price instead. Always pay the `amount` the 402 quotes; [Pricing](https://docs.limitguard.ai/pricing.md) lists every endpoint. The full body is on the [x402 Protocol](https://docs.limitguard.ai/x402-protocol.md) page.

### Supported Networks

| Network | CAIP-2 Chain ID | USDC Contract |
| - | - | - |
| Base Mainnet | `eip155:8453` | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
| Base Sepolia (testnet) | `eip155:84532` | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |
| Solana Mainnet | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` |
| Solana Devnet | `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1` | `4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU` |

The production API (`api.limitguard.ai`) quotes Base Mainnet and Solana Mainnet only: its `/.well-known/x402.json` says `testnet_supported: false`. The two testnets work only against a test environment that lists them in its `accepts` array.

### V1 Backward Compatibility

`PAYMENT-SIGNATURE` is the x402 V2 header and is recommended for new integrations; it takes priority when both are sent. The older `X-PAYMENT` header (V1) is still accepted.

### Response Headers on Success

| Header | Value | Description |
| - | - | - |
| `X-Payment-Verified` | `true` | Payment accepted and verified |
| `X-Payment-Amount` | `290000` | Amount in USDC 6-decimal units |
| `X-Payment-Fallback` | `true` | Circuit breaker triggered (rare) |

## Free Endpoints

These endpoints never require payment or authentication:

| Endpoint | Purpose |
| - | - |
| `GET /health` | API health status |
| `POST /v1/keys/create` | Self-service key provisioning |
| `GET /.well-known/x402.json` | x402 service listing |
| `GET /.well-known/agent.json` | A2A agent card |
| `GET /.well-known/mcp.json` | MCP manifest |
| `GET /.well-known/security.txt` | Security contact (RFC 9116) |
| `GET /v1/self-verify` | Limitguard's own trust score |
| `GET /v1/methodology` | Scoring methodology |
| `GET /v1/legal/*` | Legal documents |
| `GET /llms.txt` | LLM-readable summary |
| `GET /llms-full.txt` | LLM-readable full reference |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.