---
name: x402-commerce
description: Purchase prepaid agent credits for Karma.Domains Public API and MCP via x402 USDC (exact scheme, Base + Solana, retry same URL).
---

# Karma.Domains x402 Agent Credits

Autonomous agents pay with USDC through the [x402](https://www.x402.org/) protocol. No browser account, no JWT — after the first purchase you receive a long-lived **API key** and spend **agent credits** from your **balance**.

Supported payment rails (exact scheme, USDC):

| Rail | Network ID (CAIP-2) |
| ---- | ------------------- |
| Base (EVM) | `eip155:8453` (mainnet) |
| Solana | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` (mainnet) |

Each HTTP 402 response lists **6 accepts** (3 credit packs × 2 networks). Pick the entry matching your wallet chain.

## Pricing channels (do not mix)

| Channel | Audience | Payment | API billing |
| ------- | -------- | ------- | ----------- |
| UI credits | Humans in browser | Card (Dodo) | Open reports in UI |
| **agent.credits.*** | **Wallet agents** | **x402 USDC** | **Debit `balance` on API/MCP** |
| Pro subscription | Human automation | Dodo | Catalog access, no per-report debit |

Active **Pro** human accounts cannot buy agent packs — use the Pro API key instead.

## Credit packs (`agent.credits.*`)

| Plan ID | Credits | Price (USDC) |
| ------- | ------- | -------------- |
| `agent.credits.pack_100` | 100 | 1.50 |
| `agent.credits.pack_500` | 500 | 6.00 |
| `agent.credits.pack_2000` | 2000 | 20.00 |

## Operation costs (agent accounts)

| Operation | Credits |
| --------- | ------- |
| Full report (`GET /v1/reports/report?report_type=…&report_id=…`, MCP `get_domain`) | 1 |
| MCP `interpret_query` | 3 |
| MCP `search_reports` | 0 (list-row quota only, like Public API search) |
| MCP live checkers (`check_domain_expiry`, `get_domain_karma_metric`, `domain_authority_checker`, `spam_score_checker`, …) | 1 per domain (cache hits free); HTTP 402 if insufficient |
| Public API live checkers (`GET /v1/domains/checker/*`) | 1 per domain (cache hits free); HTTP 402 if insufficient |

List/search/favorites: no debit beyond list-row quota. Live checkers debit spendable `balance` (1/domain).

## Agent identity (one api_key, many wallets)

- **First purchase** (no Bearer): pay with any supported chain → receive `X-Karma-Api-Key`. One agent account is created and the payer wallet is linked.
- **Top-up or paying from another chain**: send **`Authorization: Bearer <api_key>`** together with `PAYMENT-SIGNATURE`. Credits always go to the Bearer account; the new payer wallet is linked to the same agent.
- **Do not** pay on a second chain without Bearer — that creates a separate agent account.

`extensions.karma.keep_api_key` is always `true` on 402 responses.

## Discovery

Static discovery (tooling) and live pricing (authoritative):

1. **OpenAPI** (Public API): `https://api.karma.domains/openapi.json`
2. **x402 well-known manifest** (compat): `https://api.karma.domains/.well-known/x402` and `https://mcp.karma.domains/.well-known/x402`
3. **MCP server card**: `https://karma.domains/.well-known/mcp/server-card.json`
4. **Live HTTP 402** on paid Public API routes, or **HTTP 401** on unauthenticated `POST https://mcp.karma.domains/mcp` (OAuth challenge **and** `PAYMENT-REQUIRED` / `extensions.bazaar`). MCP Bazaar includes `toolName` + `inputSchema` per tool. Authenticated MCP with insufficient agent credits still returns **402**.

Payment / top-up flow:

1. Call any protected route on `https://api.karma.domains` **without** credentials → **HTTP 402**. On MCP (`POST https://mcp.karma.domains/mcp`) the same unauthenticated call is **HTTP 401** with `WWW-Authenticate` plus the same **`PAYMENT-REQUIRED`** offer.
2. Read **`PAYMENT-REQUIRED`** header (base64 JSON, x402 v2) and `extensions.karma` in the body. On MCP, ignore OAuth if you are a wallet agent.
3. Choose a pack from `accepts[]` matching your wallet network (`network` field) and desired `amount` / `extra.plan_id`.
4. **Retry the same URL** with:
   - `PAYMENT-SIGNATURE`: base64 payment payload
   - `X-Karma-Plan-Id`: e.g. `agent.credits.pack_100` (disambiguates matching amounts)
5. On first purchase, response includes **`X-Karma-Api-Key`** — store it.
6. Normal usage: `Authorization: Bearer <api_key>` only (no x402 headers).
7. Top-up when balance is low: **Bearer + PAYMENT-SIGNATURE** on the same URL; keep the same api_key.

## Headers

| Header | Direction | Purpose |
| ------ | --------- | ------- |
| `PAYMENT-REQUIRED` | Server → client | 402: accepted packs + `extensions.karma` |
| `PAYMENT-SIGNATURE` | Client → server | Signed USDC authorization |
| `PAYMENT-RESPONSE` | Server → client | Settlement confirmation |
| `X-Karma-Plan-Id` | Client → server | Which pack to settle |
| `X-Karma-Api-Key` | Server → client | Issued on first purchase |

## Endpoints

- Public API: `https://api.karma.domains/v1/…`
- MCP: `https://mcp.karma.domains/mcp`
- Profile (balance): `GET /v1/user` with Bearer api_key
- OpenAPI: `https://api.karma.domains/openapi.json`

## Example flow (curl sketch)

```bash
# 1) Discover payment requirements (6 accepts: 3 packs × Base + Solana)
curl -i https://api.karma.domains/v1/user

# 2) First purchase — payment only, pick EVM or Solana accept
curl -i https://api.karma.domains/v1/user \
  -H "PAYMENT-SIGNATURE: BASE64_PAYLOAD" \
  -H "X-Karma-Plan-Id: agent.credits.pack_100"

# 3) Top-up or pay from another chain — Bearer required
curl -i https://api.karma.domains/v1/user \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "PAYMENT-SIGNATURE: BASE64_PAYLOAD" \
  -H "X-Karma-Plan-Id: agent.credits.pack_100"

# 4) Normal usage
curl https://api.karma.domains/v1/user \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Use an x402-compatible client SDK to build `PAYMENT-SIGNATURE` (exact scheme, USDC on Base or Solana).

## Related skills

- [karma-domains-mcp](../karma-domains-mcp/SKILL.md) — MCP tools and workflows
- [API catalog](https://karma.domains/.well-known/api-catalog) — RFC 9727 service discovery