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

# Pay per request (x402)

> Use the API without an account via USDC micropayments

Every metered endpoint accepts [x402](https://www.x402.org) payments as an alternative to an API token: no signup, no key — each request is paid for with a signed USDC transfer authorization that CompliAPI settles on-chain via a facilitator. The current price is **\$0.01 per request** (always quoted authoritatively in the challenge), paid in USDC on **Base**.

CompliAPI speaks both protocol versions: **x402 v2** (the current spec — challenge in the `PAYMENT-REQUIRED` response header, payment in the `PAYMENT-SIGNATURE` request header, CAIP-2 network ids like `eip155:8453`) and **x402 v1** (challenge in the response body, `X-PAYMENT` request header). Current x402 clients use v2 automatically; existing v1 integrations keep working unchanged.

## How it works

1. Call any metered endpoint with no `Authorization` header. Instead of a `401`, you get a `402 Payment Required` whose body is the x402 challenge:

```bash theme={null}
curl https://api.compliapi.com/api/v1/screen/email/test@example.com
```

```json theme={null}
{
  "x402Version": 1,
  "error": "payment required: no API token or X-PAYMENT header provided",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "10000",
      "resource": "https://api.compliapi.com/api/v1/screen/email/test@example.com",
      "payTo": "0x7c221925dd7494dA6F5E2254043DC8D61273309c",
      "maxTimeoutSeconds": 300,
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ],
  "options": [ ... ]
}
```

`maxAmountRequired` is in USDC base units (6 decimals): `"10000"` = \$0.01. `asset` is the USDC contract on the offered network.

2. Sign an [EIP-3009](https://eips.ethereum.org/EIPS/eip-3009) `transferWithAuthorization` for that amount to `payTo`, and retry the same request with the payment as a base64 `X-PAYMENT` header. Any x402-compatible client does this loop for you — for example [`x402-fetch`](https://www.npmjs.com/package/x402-fetch) in JS/TS wraps `fetch` so paid retries are automatic:

```ts theme={null}
import { wrapFetchWithPayment } from "x402-fetch";

const fetchWithPayment = wrapFetchWithPayment(fetch, walletClient);
const res = await fetchWithPayment(
  "https://api.compliapi.com/api/v1/screen/email/test@example.com"
);
```

3. A successful response carries a base64 settlement receipt in the `X-PAYMENT-RESPONSE` header:

```json theme={null}
{ "success": true, "transaction": "0x…", "network": "base", "payer": "0x…" }
```

## x402 v2

Every `402` also carries the v2 challenge, base64-encoded in the `PAYMENT-REQUIRED` response header. Decoded, it is the v2 `PaymentRequired` object — same price and receiving address, with CAIP-2 network ids, `amount` instead of `maxAmountRequired`, a top-level `resource` object describing the endpoint, and machine-readable input/output schemas under `extensions.bazaar`:

```json theme={null}
{
  "x402Version": 2,
  "error": "payment required: no API token or X-PAYMENT/PAYMENT-SIGNATURE header provided",
  "resource": {
    "url": "https://api.compliapi.com/api/v1/screen/email/test@example.com",
    "description": "Screen an email address against OFAC SDN and other global sanctions lists. …",
    "mimeType": "application/json",
    "serviceName": "CompliAPI",
    "tags": ["sanctions", "ofac", "email", "kyc", "compliance"],
    "iconUrl": "https://compliapi.com/compliapi-icon.svg"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "10000",
      "payTo": "0x7c221925dd7494dA6F5E2254043DC8D61273309c",
      "maxTimeoutSeconds": 300,
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ],
  "extensions": { "bazaar": { "info": { "…": "…" }, "schema": { "…": "…" } } }
}
```

A v2 client sends its signed payment base64-encoded in the `PAYMENT-SIGNATURE` request header (echoing the `extensions` block, per spec) and receives its settlement receipt in the `PAYMENT-RESPONSE` response header, with the network as a CAIP-2 id.

### Discovery (x402 Bazaar)

The paid endpoints are discoverable in the [x402 Bazaar](https://docs.cdp.coinbase.com/x402/bazaar), Coinbase's catalog of x402 resources for autonomous agents (browsable at [agentic.market](https://agentic.market) and [x402scan.com](https://www.x402scan.com)). The `extensions.bazaar` block in each challenge carries the endpoint's input schema (path and query parameters) and a realistic output example, so agents can construct valid calls without reading these docs.

## Guarantees

* **You are never charged for a failed request.** Settlement happens only after your request succeeds; if screening errors, the authorization is left unsettled and nothing moves on-chain. Retry with a fresh authorization (x402 clients sign one per attempt automatically).
* **Unsettled data is never released.** If settlement fails, the response is withheld and you get a fresh 402 — pay again to retry.
* **Authorizations are single-use.** Replaying an `X-PAYMENT` header after settlement returns a 402 asking for a fresh authorization.
* An API token under quota always wins: if you send both a valid `Authorization` and an `X-PAYMENT` header, the request is funded by your quota and no payment is taken.

## Over quota? Pay to keep going

With a valid API token but an exhausted monthly quota, the API returns a `402` (rather than the plain `429`) whose `options` include both paying per request and [upgrading your plan](https://app.compliapi.com/dashboard/plans) — so batch jobs can spill over into pay-per-request instead of failing.

## MCP

The [MCP server](/mcp) takes the same payments. Connect **without** an `Authorization` header — `initialize` and `tools/list` work anonymously — and unpaid tool calls return an error result whose structured content is the same challenge object shown above. Pay by adding the `X-PAYMENT` header to the MCP connection (or the `x402/payment` key in the request `_meta` for non-HTTP transports); the settlement receipt comes back in the tool result's `_meta` under `x402/payment-response`.

```json theme={null}
{
  "mcpServers": {
    "compliapi": {
      "url": "https://api.compliapi.com/mcp",
      "headers": { "X-PAYMENT": "<base64 payment payload>" }
    }
  }
}
```