Account and balance
Your balance, your ledger and your own activity are readable with your API key. Everything here is scoped to your account — there is no parameter that widens it.
Who am I
{"ok": true, "principal": {"consumerId": "…", "apiKeyId": "…",
"name": "research-team-a", "scopes": ["jobs:create","jobs:read",
"results:read","audit:read"]}}
Balance
{"ok": true, "balance": {
"balanceMicros": 50000000, "display": "50 USD",
"toppedUpMicros": 50000000, "chargedMicros": 0, "currency": "USD"}}
import os
import requests
API = os.environ.get("API", "https://bankworks.info")
http = requests.Session()
http.headers["Authorization"] = f"Bearer {os.environ['API_KEY']}"
balance = http.get(f"{API}/v1/me/balance", timeout=30)
balance.raise_for_status()
info = balance.json()["balance"]
print("balance:", info["display"], f"({info['balanceMicros']} micros)")
# Amounts are integer micros: 1,000,000 micros is one unit of currency.
history = http.get(f"{API}/v1/me/transactions", params={"limit": 10}, timeout=30)
history.raise_for_status()
for txn in history.json()["transactions"]:
print(txn["createdAt"], txn["kind"], txn["amountMicros"], "->", txn["balanceAfterMicros"])
const API = process.env.API ?? "https://bankworks.info";
const API_KEY = process.env.API_KEY;
if (!API_KEY) throw new Error("Set API_KEY first");
async function get(path) {
const response = await fetch(`${API}${path}`, {
headers: { Authorization: `Bearer ${API_KEY}` },
});
if (!response.ok) throw new Error(`HTTP ${response.status} for ${path}`);
return response.json();
}
const { balance } = await get("/v1/me/balance");
console.log("balance:", balance.display, `(${balance.balanceMicros} micros)`);
// Amounts are integer micros: 1,000,000 micros is one unit of currency.
const { transactions } = await get("/v1/me/transactions?limit=10");
for (const txn of transactions) {
console.log(txn.createdAt, txn.kind, txn.amountMicros, "->", txn.balanceAfterMicros);
}
curl -sS -H "Authorization: Bearer $API_KEY" "$API/v1/me/balance"
curl -sS -H "Authorization: Bearer $API_KEY" \
"$API/v1/me/transactions?limit=10&offset=0"
Amounts are integer micros
One unit of currency is 1,000,000 micros. Money never
touches a floating-point number anywhere in this system, and neither
should it in yours: 0.1 + 0.2 is the oldest defect in
accounting software.
50 USD → 50000000 micros
0.001 USD (one tenth of a cent) → 1000 micros
Transaction history
Every movement is one append-only row recording the balance it produced, so any figure can be walked backwards without replaying the whole history.
| Kind | Sign | Meaning |
|---|---|---|
TOPUP | + | Funds added |
CHARGE | − | Usage billed |
REFUND | + | A charge reversed |
ADJUSTMENT | ± | A manual correction, always with a note |
What is billed
Successful requests. A URL task that ends DONE,
or a session fetch that returns its result, is one billed request. One that
fails, is blocked, or is retried is not. You pay for pages we actually
handed you.
Where a request is paid from
- First, the allowance of your monthly plan, if you have a paid one.
- Then your balance, at the per-request price on the pricing page (the price per 1,000 divided by 1,000).
Each charge to the balance appears in GET /v1/me/transactions as a
CHARGE row such as “Usage: 120 successful requests”. Requests covered
by your plan do not create a row: the plan's used count rises instead.
When there is nothing left
A new job, session or fetch that your allowance and balance cannot pay for is
refused before anything is stored, with 402:
HTTP/1.1 402 Payment Required
{"ok": false, "code": "payment_required",
"error": "Not enough balance or plan allowance for 500 request(s). You can start 120. ...",
"available": 120, "requested": 500}
available is how many requests you could start right now, counting work
already running. Add funds or choose a plan in the portal, or send fewer URLs, and
retry. Work that was already running when the balance ran out still finishes.
CHARGE rows appear while you run traffic,
nothing is being deducted yet.
Your API activity
Returns your own requests with status code, path, method and timestamp. Useful for confirming a rotated key has taken over before you revoke the old one.
The customer portal
The portal shows the same data in a browser — balance, transactions, jobs, keys and usage — with a separate email and password login. Your API key is not a portal credential, and the portal password is not an API credential.