Overview
Base URL: https://nbx4.dev. All addresses are 20-byte EVM hex values. Report IDs have the form nbx4_ followed by 64 lowercase hex characters. The report is created before payment and stored in D1. A paid read returns the stored snapshot, not a fresh RPC call.
The request flow is POST /v1/prepare → report_id → GET /v1/reports/{report_id} → HTTP 402 payment requirements → a compatible x402 client's retry → report JSON. A regular browser does not automatically pay x402.
Endpoints
POST /v1/prepare
Prepare a snapshot. Content-Type must be application/json; the body must contain only address. Maximum request body: 1,024 characters. When available, preparation returns HTTP 201. Upstream or quota failures return 502 or 429.
curl -i -X POST 'https://nbx4.dev/v1/prepare' -H 'Content-Type: application/json' --data '{"address":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}'When enabled, HTTP 201 contains report_id, status: "ready" and payment_path. It never contains paid findings. The same address at the same block reuses the stored report unless the block hash conflicts, in which case the service refuses the snapshot.
GET /v1/reports/{report_id}
For a known report, an unpaid request receives HTTP 402 with a Base64-encoded JSON offer in the PAYMENT-REQUIRED response header. It does not disclose findings. A missing ID returns 404 before payment middleware runs. A settled payment returns the immutable report as JSON. One prior paid browser test was independently checked against Base settlement and its matching stored report. This does not verify new report preparation or guarantee future settlement.
GET /health
Returns {"service":"nbx4","status":"up","payments_ready":true|false}. The flag means the payment middleware is configured. It is not a settlement or business-readiness signal.
GET /logo.svg
Standalone SVG brand asset. The same URL is advertised in the x402 offer metadata.
x402 offer
Current offer: x402 version 2, exact scheme, Base Mainnet eip155:8453, USDC asset 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, and 20,000 atomic units (0.02 USDC) per paid read. The offer includes serviceName: "nbx4", iconUrl and a short description. A client must check the offer before taking any payment action.
Standard exact EVM payment signatures cover transfer terms. The EIP-3009 signature covers the transfer, not the report ID. The request URL selects the delivered report; before settlement the same authorization could be presented for another report with identical price and recipient. Treat this as one report read per successful payment, not a pre-bound purchase of a particular report. A settled nonce cannot be paid again. Never reuse a signature across requests; if settlement is uncertain, check the receipt before retrying.
Report format
| Field | Meaning |
|---|---|
report_id, report_digest | SHA-256 of canonical report data; the ID includes the digest. |
chain_id, address | Base Mainnet (8453) and submitted contract address. |
block_number, block_hash, observed_at | Pinned observation, checked for a changed hash during the read, with report creation time. |
verdict_label | REVIEW when one of the implemented signals is present; otherwise INDETERMINATE. Neither means safe or malicious. |
summary, top_reasons | One sentence and at most three reasons. Reasons include code, severity, text, unknowns and evidence. |
unknowns, policy_version | Limits of this check and the version of its decision rules. |
card.svg | Shareable SVG embedded as a string in the paid JSON response. |
The current analyzer writes the natural-language summary and top_reasons.text fields in Polish. Stable field names and verdict codes are in English.
Errors
| Status | Typical error code | What it means |
|---|---|---|
| 400 / 413 / 415 | invalid_address, invalid_json, body_too_large, json_required | The preparation request is malformed or too large. |
| 402 | Payment requirements in header | Known report, no valid x402 payment supplied; no findings returned. |
| 404 / 405 | not_found, method_not_allowed | Unknown report or unsupported report method. |
| 422 / 429 | not_contract, rate_limited, daily_quota_reached | No contract code at the observed block, or request limit reached. |
| 502 / 503 | analysis_unavailable, not_active, storage_unavailable, snapshot_conflict | Upstream, activation or integrity check prevented a safe response. |
Error bodies generated by nbx4 have the shape {"error":"code"}. The x402 middleware may return its own payment response shape.
Scope and limits
The service calls eth_getCode, reads the EIP-1967 implementation slot with eth_getStorageAt, and invokes owner() with eth_call. It also checks chain ID and block hash consistency. It does not determine actual admin permissions, non-standard proxies, mintability, token transfer restrictions, liquidity, holder concentration, or whether trading is possible.
Preparation is subject to Cloudflare rate-limit bindings (nominally 4 requests per minute per location and 2 per IP per minute). Counters are eventually consistent; a separate atomic D1 quota caps preparation at 50 per UTC day globally, before upstream RPC. Contract reads use CDP Node on Base Mainnet; the client key is excluded from report evidence. Treat snapshots as time-bound evidence and independently verify important decisions.