Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Use an API key

No API key is required to use oculr: agents and apps pay per request over MPP, and that stays the default. An API key is the alternative for callers that cannot hold a wallet, such as a script, a server or an alert pipeline. It spends a prepaid balance instead.

When to use a key

  • Use MPP (the quickstart) when your code or agent can hold a funded wallet. Nothing to sign up for, nothing to rotate.
  • Use an API key when the caller is a script, a backend service or an incident workflow that should spend a balance you already hold, with no MPP client and no wallet on the machine.

A key works on the same analysis endpoints and returns the same ExplanationResult. A run costs the same as on any other path; see Pricing.

There are two kinds of key, which differ only in who holds the balance they spend.

Keys for a Google account (self-serve)

If you use the web app with a Google sign-in, you can create keys that spend that account's balance, which you top up by card.

  1. Sign in to oculr.xyz/app with Google.
  2. Open the balance menu and choose API keys.
  3. Give the key a name (for example, the integration that will use it) and choose Create key. You may be asked to sign in again first: creating a key needs a recent sign-in.
  4. Copy the key. It is shown once and never again. Store it in your secret manager.

Keys start with oc_live_. An account can hold up to 5 active keys and make up to 20 key creation attempts per UTC day; an attempt that is refused (for example because 5 keys are already active) still counts. Keys are for Google sign-in accounts; wallet sign-in accounts cannot create them.

Keys for an organisation

An organisation that wants oculr in an alert or incident workflow, and whose platform holds an API key rather than a wallet, can have an organisation account. There is no self-serve signup for organisations: contact oculr and we set up the organisation and issue its keys.

An organisation buys credit in advance. oculr invoices the organisation and credits its balance when the invoice is paid. Every key the organisation holds spends that one balance.

Organisation keys are used exactly like the self-serve keys above, as described in Call the API below, with the same Authorization header.

Call the API

Send the key as a bearer token on every request:

Authorization: Bearer oc_live_...

The API is at https://mpp.oculr.xyz. Two ways to run an analysis:

Stream: POST /explain

The streaming endpoint sends progress events and then the result as server-sent events. Ask for the stream with Accept: text/event-stream. The request body is the same as for POST /explain.

curl -N https://mpp.oculr.xyz/explain \
  -H "Authorization: Bearer $OCULR_API_KEY" \
  -H 'Accept: text/event-stream' \
  -H 'Content-Type: application/json' \
  -d '{"txHash":"0x..."}'

The same in Node, reading the stream with plain fetch:

const res = await fetch('https://mpp.oculr.xyz/explain', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.OCULR_API_KEY}`,
    Accept: 'text/event-stream',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ txHash: '0x...' }),
})
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`)
 
const decoder = new TextDecoder()
let buffer = ''
let result
for await (const chunk of res.body!) {
  buffer += decoder.decode(chunk, { stream: true })
  let end
  while ((end = buffer.indexOf('\n\n')) !== -1) {
    const frame = buffer.slice(0, end)
    buffer = buffer.slice(end + 2)
    const data = frame.split('\n').filter((l) => l.startsWith('data:')).map((l) => l.slice(5).trim()).join('')
    if (!data) continue
    const msg = JSON.parse(data)
    if (msg.type === 'meta') console.log('requestId', msg.requestId)
    if (msg.type === 'result') result = msg
    if (msg.type === 'error') throw new Error(`${msg.code}: ${msg.message}`)
  }
}

The first event carries a requestId. Keep it: it names the run if you need to stop it or recover its report.

Submit and poll: POST /explain/async

For an alert pipeline that would rather not hold a connection open, submit the job and poll GET /result/:jobId with the same key:

SUBMIT=$(curl -sS -X POST https://mpp.oculr.xyz/explain/async \
  -H "Authorization: Bearer $OCULR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"txHash":"0x..."}')
JOB=$(echo "$SUBMIT" | jq -r '.jobId // empty')
[ -n "$JOB" ] || { echo "$SUBMIT"; exit 1; }   # no jobId: refused, see Errors below
 
while :; do
  JOB_JSON=$(curl -sS https://mpp.oculr.xyz/result/$JOB -H "Authorization: Bearer $OCULR_API_KEY")
  case "$(echo "$JOB_JSON" | jq -r .status)" in
    pending|running) sleep 5 ;;
    *) break ;;
  esac
done
 
echo "$JOB_JSON" | jq .

The same in Node, with plain fetch:

const auth = { Authorization: `Bearer ${process.env.OCULR_API_KEY}` }
 
const submit = await fetch('https://mpp.oculr.xyz/explain/async', {
  method: 'POST',
  headers: { ...auth, 'Content-Type': 'application/json' },
  body: JSON.stringify({ txHash: '0x...' }),
})
if (submit.status !== 202) throw new Error(`${submit.status} ${await submit.text()}`)
const { jobId } = await submit.json()
 
let job
while (true) {
  await new Promise((r) => setTimeout(r, 5000))
  const res = await fetch(`https://mpp.oculr.xyz/result/${jobId}`, { headers: auth })
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`)
  job = await res.json()
  if (job.status === 'complete' || job.status === 'error') break
}
if (job.status === 'error') throw new Error(`${job.errorCode ?? 'error'}: ${job.error}`)
console.log(job.result) // plus job.html when the request set "report": true

With a key, polls are free: the analysis is charged to your balance as it runs, whether or not you poll, so poll as often as your pipeline needs. The job's status moves from pending to running to complete (or error), and a job expires one hour after its last update (for a finished job, one hour after it completes).

Only the account that paid for a job can read it. A poll for that job with another account's valid key gets 404, the same answer as for an unknown job. A poll with a revoked or unknown key gets 401 (see the table below). A poll with no key at all gets a 402 payment challenge.

Check your balance

GET /account/key returns the calling key's name and the balance it spends:

curl -sS https://mpp.oculr.xyz/account/key -H "Authorization: Bearer $OCULR_API_KEY"
{ "keyId": "...", "name": "alerts-prod", "freeUsd": 42.5, "spendCapUsd": 25, "spentTodayUsd": 3.1 }

spendCapUsd and spentTodayUsd are the key's daily limit and what it has spent since 00:00 UTC, both null when the key has no limit. Only a self-serve key (one created in the web app) returns them: an organisation key returns { "keyId", "name", "freeUsd" }, and its name can be null.

An organisation key can also call GET /account/org, which returns { "orgId", "name", "freeUsd" }. Watch the balance from your pipeline so you top up before it runs out, rather than finding out from a 402.

How runs are paid

  • Each run needs $2.00 of balance to start. That is the same rule as in the web app, and it applies to every run at once: five analyses started together need $10.00 free.
  • The run is charged as it goes, from the balance the key spends. The total is the run's price; see Pricing.
  • If the balance runs out mid-run, the run can take the balance up to $7.00 below zero, and past that point it stops. How far below zero depends on how much the account has topped up or been credited; an account's first run cannot go below zero at all. What you receive depends on the endpoint:
    • On POST /explain/async, the job completes with the partial report the run had reached, and you pay only what was collected. Check confidence and a summary starting "Partial result", as for any partial result.
    • On the POST /explain stream, the stream ends with an error event with code: "charge_incomplete" and the run's requestId. Top up, then recover the report.
  • A failed job is charged only for what ran. If an async job ends in error (for example, the transaction is on no supported chain), what it spent before failing has already been charged, and nothing more is charged for it.

Self-serve accounts top up by card in the web app. Organisations are credited by oculr after an invoice is paid.

Errors

StatusBodyMeaning
402{ "code": "top_up_required", "freeUsd", "requiredUsd" }A self-serve account's balance is below the $2.00 needed to start a run. Top up in the web app.
402{ "code": "org_balance_exhausted", "freeUsd", "requiredUsd" }An organisation's balance is below the $2.00 needed to start a run. Contact oculr to add credit.
402{ "code": "key_spend_cap_reached", "spendCapUsd", "spentTodayUsd" }A self-serve key has reached the daily limit set on it in the web app's API keys panel. The limit resets at 00:00 UTC. A run that reaches the limit part-way stops early and returns the partial result it had reached. Raise or remove the limit in the panel, or wait for the reset.
401{ "error": "Invalid or revoked API key", "code": "invalid_api_key" }The key was not recognised: it is revoked, mistyped, or not enabled. Nothing ran and nothing was charged. Returned on every route that takes a key.
401{ "error": "Unauthorized" }From GET /account/key or GET /account/org: the request carries no key of the right kind (/account/org needs an organisation key).
403{ "error": "account_frozen" }The account is frozen (for example, after a disputed card payment) and cannot start runs. Contact oculr.
404{ "error": "Job not found - expired or invalid ID" }From GET /result/:jobId: the job expired, does not exist, or belongs to another account.

List your runs and get reports

Every run a key pays for is kept in its account's history, the same list as My reports in the web app. Read it with the same key:

  • GET /runs lists your runs, newest first, with each run's id, txHash, chain and price. Page with limit and offset.
  • GET /runs/{id} returns one run with the full report it delivered, for example GET /runs/4815162342.

Both are free. See GET /runs.

Stop a run or recover a report

Both take the requestId from the first event of a stream, and both accept the key that paid for the run:

  • POST /explain/cancel/{requestId} stops a streaming run. You pay for what ran up to that point.
  • GET /explain/run/{requestId} returns { requestId, txHash, status, frames }, and the last of the frames is the run's result (or report). For a run that stopped with charge_incomplete, it first collects the part of the price still owed from your balance. If the balance still cannot cover it, you get 402 and can top up and retry. Right after charge_incomplete it can answer 409 with code: "run_settling" while the run's charge settles: retry after a few seconds.

Rotate and revoke

To rotate a key without downtime:

  1. Create the new key (in the web app, or ask oculr for an organisation key).
  2. Deploy it everywhere the old key is used.
  3. Revoke the old key.

Revocation takes effect on the next request. Keys keep working after you sign out of the web app, until you revoke them, so revoke any key you no longer use.

What a key cannot do

A key can run analyses, read its own jobs and runs, and read its balance. It cannot create, rename or revoke keys, and it cannot withdraw funds: those need you signed in to the web app.

Related