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

# Credits

> How usage is metered — and how agents top up their own balance.

Every verification costs **one credit**. Credits cost **\$0.05 each**, paid in USDC on Base.

## Free credits

New accounts start with **50 free credits** — enough to wire Chance into your agent and see it working end to end. No card required.

You can watch your balance in the [dashboard](https://harness.chance.cc/dashboard); each response also returns `creditsRemaining`, and `GET /api/v1/credits` returns the balance plus top-up terms.

## Running out

When your balance hits zero, the API returns `402 Payment Required`:

```json theme={null}
{
  "error": "out_of_credits",
  "message": "No credits remaining. Top up with USDC on Base via x402: POST https://harness.chance.cc/api/v1/credits/topup?credits=N (1 credit = $0.05, 20-10000 credits per payment). See GET https://harness.chance.cc/api/v1/credits for details.",
  "topup": {
    "protocol": "x402",
    "method": "POST",
    "url": "https://harness.chance.cc/api/v1/credits/topup?credits=N",
    "network": "eip155:8453",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "priceUsdPerCredit": 0.05,
    "minCredits": 20,
    "maxCredits": 10000
  }
}
```

Your agent should treat a `402` on a **verification** call as "verifier unavailable" and **fail closed** — don't execute an unverified action. It can then top up and retry.

<Note>
  The out-of-credits `402` on verification endpoints (`/api/v1/intent`, wallet propose, MCP) is **not** itself x402-payable — it carries no `PAYMENT-REQUIRED` header, only the JSON `topup` pointer above. If you wrap those calls with an x402 client (e.g. `wrapFetchWithPayment`), it will throw trying to parse payment terms; catch it, read the `topup` pointer from the body, and pay at the dedicated `/api/v1/credits/topup` endpoint. Only `/api/v1/credits/topup` speaks the full x402 payment handshake.
</Note>

## Top-ups (x402)

The top-up endpoint speaks [x402 v2](https://docs.cdp.coinbase.com/x402/welcome) — the HTTP-native payment protocol — so agents can refill their own balance autonomously, with no card and no human in the loop:

```
POST /api/v1/credits/topup?credits=200        x-api-key: chance_sk_…
```

1. The first call returns `402` with a `PAYMENT-REQUIRED` header: exact scheme, USDC on Base mainnet (`eip155:8453`), amount = credits × \$0.05.
2. Your x402 client signs an EIP-3009 `transferWithAuthorization` — **gasless**: the wallet only needs USDC, never ETH — and retries with a `PAYMENT-SIGNATURE` header.
3. The payment settles on-chain (typically \~1s) and the credits land on **the account that owns the API key**, no matter which wallet paid. The response carries the new balance and the settlement tx hash in the `PAYMENT-RESPONSE` header.

With `@x402/fetch` the whole dance is one wrapper:

```ts theme={null}
import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PAYER_KEY);
const client = new x402Client().register("eip155:8453", new ExactEvmScheme(account));
const fetchWithPay = wrapFetchWithPayment(fetch, client);

const res = await fetchWithPay(
  "https://harness.chance.cc/api/v1/credits/topup?credits=200",
  { method: "POST", headers: { "x-api-key": process.env.CHANCE_API_KEY } },
);
// → { credited: 200, usd: "10.00", creditsRemaining: 203, txHash: "0x…" }
```

Retries are safe: crediting is idempotent per payment authorization (the EIP-3009 nonce), so resubmitting the same signed payment can never double-credit — you'll get the original result back with `"replayed": true`.

### Naming the account: API key or public code

Two ways to say **which account** a payment credits:

* **`x-api-key: chance_sk_…`** — the owner's secret key, for your own agent. The `200` response includes the running `creditsRemaining`.
* **`?account=chance_topup_…`** — a **public account code** (find it under **Top up** in the dashboard). It can only *add* credits, so it's safe to paste into any third-party agent to have it pay on your behalf. No API key needed; the balance is not revealed in the response.

Every account has a top-up page in the dashboard that generates the code and a ready-to-paste instruction for an agent, linking a machine-readable guide at `GET /api/v1/credits/topup/guide`.

### Payer wallet requirements

* A **plain EOA** holding USDC on Base mainnet. Works with viem local accounts, CDP server wallets, and Privy server wallets.
* On the legacy v1 `x402-fetch` package, payments above **0.1 USDC** are blocked by a default `maxValue` — pass a higher `maxValue` or (better) use the v2 `@x402/*` packages shown above.

### Limits

|                 |                                    |
| --------------- | ---------------------------------- |
| Price           | \$0.05 per credit                  |
| Minimum         | 20 credits (\$1) per payment       |
| Maximum         | 10,000 credits (\$500) per payment |
| Network / asset | Base mainnet, native USDC          |