Read hCaptcha API balance and budget in microcents

Use exact integer balance units, account for recognition groups and task modes, and handle admission-time credit errors even after a balance read.

Preserve the integer unit

The API represents service credit as a string containing integer microcents. One USD is 100,000,000 microcents. Parse the string into an integer for budget arithmetic; format decimal dollars only when displaying an amount to a person.

import { FetchClient } from "@easycaptcha-to/sdk/fetch";

const client = new FetchClient({
  apiKey: process.env.EASYCAPTCHA_API_KEY,
});
const balance = await client.getBalance();
const credit = BigInt(balance.balance_microcents);
const wholeDollars = credit / 100_000_000n;
console.log(wholeDollars.toString());

This display intentionally shows whole dollars. It does not change the stored balance or round a planned charge. Keep credit for exact calculations and serialize it back to a string when writing JSON.

Treat a balance read as a snapshot

A read does not reserve credit for the next job. Other keys on the same account can submit work before your operation is admitted. Handle a definitive credit error from task creation even when a previous snapshot looked sufficient.

If several local workers share a budget, coordinate their scheduling. An application estimate can reduce unwanted submissions, but the server’s admission and billing remain authoritative. Avoid assuming a local subtraction fully reproduces remote billing.

Use the actual pricing unit

Recognition is priced per group, not necessarily per complete challenge. Token work has its own rate. Burst and fast can change a paid task’s multiplier. Consult pricing and the modes contract rather than using one hard-coded cost for every request.

Report refunds or reversals in the same accounting period as the related activity when practical, and distinguish a top-up from credits earned through an affiliate program. A deposit amount, a credited balance, and a task cost are different measures.

Make low-credit recovery useful

A background worker should surface low credit as a clear operational condition instead of retrying creation in a tight loop. Stop admitting new work according to your application policy and direct the account owner to payments. Preserve known task IDs so balance recovery does not create duplicates.

See cost per outcome for evaluation reporting and burst and fast integration for estimating work that uses optional modes.