Bankworks

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

GET /v1/me
JSON
{"ok": true, "principal": {"consumerId": "…", "apiKeyId": "…",
 "name": "research-team-a", "scopes": ["jobs:create","jobs:read",
 "results:read","audit:read"]}}

Balance

GET /v1/me/balance
JSON
{"ok": true, "balance": {
  "balanceMicros": 50000000, "display": "50 USD",
  "toppedUpMicros": 50000000, "chargedMicros": 0, "currency": "USD"}}
Python
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"])
Node.js
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
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.

Text
50 USD  →  50000000 micros
0.001 USD (one tenth of a cent) →  1000 micros

Transaction history

GET /v1/me/transactions?limit=50&offset=0

Every movement is one append-only row recording the balance it produced, so any figure can be walked backwards without replaying the whole history.

KindSignMeaning
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

  1. First, the allowance of your monthly plan, if you have a paid one.
  2. 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
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.

Billing is applied per account and can be switched off entirely for an account during an evaluation. Your balance and your ledger tell you which state you are in: if no CHARGE rows appear while you run traffic, nothing is being deducted yet.

Your API activity

GET /v1/me/auditaudit:read

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.

Successful status polls are not recorded. They are excluded to keep the log readable, so this is a log of meaningful calls and errors, not a count of every HTTP request you made. Do not use it to reconcile a bill.

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.