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; 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:

{
  "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.

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.

Top-ups (x402)

The top-up endpoint speaks x402 v2 — 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:

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