API reference — WalletBureau

Quickstart

# x402: your agent pays $0.05 automatically
curl https://walletbureau.com/v1/score/0x…

# or with a prepaid key
curl -H "Authorization: Bearer atk_…" \
     https://walletbureau.com/v1/score/0x…

One GET, one JSON, stable schema. Pay per call with x402 — no account, no invoice, no minimum. Or use a prepaid API key.

Endpoints

Method	Path	Auth	Returns
`GET`	`/v1/score/{address}`	`x402` or `Bearer atk_…`	Score response
`GET`	`/v1/demo/score/{address}`	none · 3 checks/day	Score response
`GET`	`/v1/stats`	none	Index counters
`GET`	`/v1/health`	none	Service status and indexer lag

Response schema

Generated from the published JSON Schema. The demo and the paid endpoint return the same shape; fields are only ever added, never renamed or removed.

Field	Type	Req.	Constraints
`address`	`string`	yes	`^0x[0-9a-f]{40}$`
`score`	`integer`	yes	`0–100`
`verdict`	`string`	yes	`ok · caution · avoid`
`flags[]`	`array`	yes
`flags[].code`	`string`	yes	`new_address · thin_history · concentration · oneoff_pattern · linked_to_flagged · sybil_suspect · activity_spike · labeled · unknown_address`
`flags[].severity`	`string`	yes	`low · med · high`
`flags[].reason`	`string`	yes	`minLength 1`
`stats.first_seen`	`string \| null`	yes	`date-time`
`stats.tx_in`	`integer`	yes	`≥ 0`
`stats.tx_out`	`integer`	yes	`≥ 0`
`stats.volume_in_usd`	`string`	yes	`^-?\d+(\.\d+)?$`
`stats.volume_out_usd`	`string`	yes	`^-?\d+(\.\d+)?$`
`stats.distinct_payers`	`integer`	yes	`≥ 0`
`stats.confidence_basis`	`string`	yes	`minLength 1`
`meta.computed_at`	`string`	yes	`date-time`
`meta.cache_age_seconds`	`integer`	yes	`≥ 0`
`meta.api_version`	`string`	yes	`= v1`
`meta.disclaimer`	`string`	yes	`minLength 1`

{
  "address": "0x8f3a1c2b9d4e5f60718293a4b5c6d7e8f9a0b1c2",
  "score": 34,
  "verdict": "avoid",
  "flags": [
    { "code": "new_address", "severity": "high",
      "reason": "First seen in x402/EIP-3009 data 4 days ago (younger than 7 days)" }
  ],
  "stats": {
    "first_seen": "2026-08-06T09:12:44.000Z",
    "tx_in": 128, "tx_out": 3,
    "volume_in_usd": "604.31", "volume_out_usd": "12.05",
    "distinct_payers": 128,
    "confidence_basis": "confirmed+probable"
  },
  "meta": {
    "computed_at": "2026-08-10T18:00:02.000Z",
    "cache_age_seconds": 312,
    "api_version": "v1",
    "disclaimer": "Risk signals, not accusations. Methodology: https://walletbureau.com/methodology"
  }
}

Error codes

Every error returns JSON with a stable machine-readable <code>error</code> field and a human-readable <code>message</code>. Match on <code>error</code>, not on the message text.

HTTP	`error`	Meaning
400	`invalid_address`	Not 0x + 40 hex characters
401	`invalid_api_key`	Unknown or disabled API key
402	`payment_required`	No payment yet — the x402 requirements are in the PAYMENT-REQUIRED header
402	`insufficient_balance`	Prepaid key has less than the price of one call
429	`demo_limit_reached`	Today's free demo checks are used up
429	`rate_limited`	Too many requests per second from one IP
503	`score_unavailable`	Scoring is temporarily unavailable — you are not charged
503	`db_unavailable`	The index is temporarily unavailable

Paying with x402

Call the endpoint without credentials, receive 402 Payment Required, settle $0.05 in USDC on Base through the x402 flow, and repeat the request. No account, no invoice, no minimum.

curl -i https://walletbureau.com/v1/score/0x…
HTTP/1.1 402 Payment Required

API keys

A prepaid key skips the payment round-trip. Send it as a bearer token. Keys are issued by hand for now — write to us.

curl -H "Authorization: Bearer atk_…" \
     https://walletbureau.com/v1/score/0x…

Rate limits

Caller	Limit	On exceed
Demo (no auth)	3 / day per IP	`429 demo_limit_reached`
Any caller	10 / second per IP	`429 rate_limited`

Risk signals, not accusations. A low score means we saw patterns worth checking — not proof of fraud. We explain every flag, and we fix mistakes: if you think a flag is wrong, write to us and a human will review it.

Read the methodology →