The API is paused. Since October 2026 the scoring API and the MCP server are offline. The methodology and articles stay here. Write to us to hear when it is back.

API reference

v1$0.01 per check · USDC on Base · settlement via x402

Quickstart

# x402: your agent pays $0.01 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.

MCP server

The same check as a tool your agent can call. The package ships ready-to-run JavaScript — no build step, no install scripts, no native modules — and exposes two tools: check_counterparty (one check, $0.01) and get_service_stats (free). The price is read from the live API at startup, so the tool annotation your agent sees is the price it will pay.

# Claude Code
claude mcp add walletbureau -- npx -y @walletbureau/mcp

# Claude Desktop, Cursor and other clients: mcpServers entry
"walletbureau": { "command": "npx", "args": ["-y", "@walletbureau/mcp"] }

How a check is paid for depends on the environment, and nothing has to be switched by hand. If both are set, the prepaid key wins — its balance is already paid for.

ModeSet thisWhat happens
Free demonothingRuns on the demo quota: 3 checks per day per IP.
Prepaid keyWALLETBUREAU_API_KEYEach check is debited from the key's balance. No crypto involved.
Wallet (x402)X402_PRIVATE_KEYThe server signs an x402 payment of $0.01 in USDC on Base per check.

Package on npm → Source on GitHub →

Endpoints

MethodPathAuthReturns
GET/v1/score/{address}x402 or Bearer atk_…Score response
GET/v1/demo/score/{address}none · 3 checks/dayScore response
GET/v1/statsnoneIndex counters
GET/v1/healthnoneService 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.

FieldTypeReq.Constraints
addressstringyes^0x[0-9a-f]{40}$
scoreintegeryes0–100
verdictstringyesok · caution · avoid
flags[]arrayyes
flags[].codestringyesnew_address · thin_history · concentration · oneoff_pattern · linked_to_flagged · sybil_suspect · activity_spike · labeled · unknown_address
flags[].severitystringyeslow · med · high
flags[].reasonstringyesminLength 1
stats.first_seenstring | nullyesdate-time
stats.tx_inintegeryes≥ 0
stats.tx_outintegeryes≥ 0
stats.volume_in_usdstringyes^-?\d+(\.\d+)?$
stats.volume_out_usdstringyes^-?\d+(\.\d+)?$
stats.distinct_payersintegeryes≥ 0
stats.confidence_basisstringyesminLength 1
meta.computed_atstringyesdate-time
meta.cache_age_secondsintegeryes≥ 0
meta.api_versionstringyes= v1
meta.disclaimerstringyesminLength 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.

HTTPerrorMeaning
400invalid_addressNot 0x + 40 hex characters
401invalid_api_keyUnknown or disabled API key
402payment_requiredNo payment yet — the x402 requirements are in the PAYMENT-REQUIRED header
402insufficient_balancePrepaid key has less than the price of one call
429demo_limit_reachedToday's free demo checks are used up
429rate_limitedToo many requests per second from one IP
503score_unavailableScoring is temporarily unavailable — you are not charged
503db_unavailableThe index is temporarily unavailable

Paying with x402

Call the endpoint without credentials, receive 402 Payment Required, settle $0.01 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

CallerLimitOn exceed
Demo (no auth)3 / day per IP429 demo_limit_reached
Any caller10 / second per IP429 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 →