Skip to main content
Glama
walletbureau

WalletBureau

Official
by walletbureau
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

@walletbureau/mcp

Check who you are about to pay. An MCP server that gives your agent one tool: score the behavioral risk of a wallet on Base before sending it money.

The score comes from the full history of x402 / EIP-3009 USDC payments on Base — how long the address has existed, who pays it, how concentrated its inflows are, whether its activity just spiked. You get a number from 0 to 100, a verdict (ok / caution / avoid) and the risk flags that produced them, each with a reason in plain language.

These are risk signals, not accusations. Methodology: https://walletbureau.com/methodology

Install

npm i @walletbureau/mcp --ignore-scripts

The package ships ready-to-run JavaScript. There are no install scripts, no native modules and no build step on your machine — --ignore-scripts changes nothing here, and that is on purpose.

Claude Code

claude mcp add walletbureau -- npx -y @walletbureau/mcp

Claude Desktop / Cursor / any MCP client

Add this to your MCP configuration (claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "walletbureau": {
      "command": "npx",
      "args": ["-y", "@walletbureau/mcp"]
    }
  }
}

That is the whole setup. With no credentials the server runs on the public free quota — a few checks per day — which is enough to try it. To keep going, pick a payment mode below.

Related MCP server: defi-yield-scanner-mcp

Paying for checks

A full check costs $0.01. The server picks its mode from the environment:

Mode

Set this

What happens

Free demo

nothing

Uses the public demo quota (a few checks per day per IP).

Prepaid key

WALLETBUREAU_API_KEY=atk_…

Each check is debited from the key's balance. No crypto involved.

Wallet (x402)

X402_PRIVATE_KEY=0x…

The server pays $0.01 in USDC on Base per check, automatically, over x402.

If both are set, the prepaid key wins — its balance is already paid for, and an on-chain payment would be a second charge.

{
  "mcpServers": {
    "walletbureau": {
      "command": "npx",
      "args": ["-y", "@walletbureau/mcp"],
      "env": { "WALLETBUREAU_API_KEY": "atk_your_key_here" }
    }
  }
}

If you pay from a wallet

X402_PRIVATE_KEY is a real spending key. Treat it like one:

  • Use a dedicated wallet funded with a small amount of USDC — not your main account.

  • The key never leaves your machine. It is used to sign x402 payments and is never logged, never sent to the service and never included in tool output. The service only ever sees the payment.

  • X402_MAX_PRICE_USD (default 0.10) caps what a single call may cost. The price is quoted by the remote server, so this check lives in code next to the signing step — not in a prompt.

Tools

check_counterparty — paid

Input: { "address": "0x…" } — a wallet address on Base.

Returns the full report: score, verdict, risk flags with reasons, and the aggregate statistics behind them. Its price is visible to your client before the call, both in the tool description and in the tool's _meta under walletbureau/pricing.

{
  "address": "0x…",
  "score": 74,
  "verdict": "ok",
  "flags": [
    { "code": "activity_spike", "severity": "low",
      "reason": "Volume over the last 24 h is 12× the median of the last 30 days" }
  ],
  "stats": {
    "first_seen": "2025-11-02T…Z", "tx_in": 1204, "tx_out": 17,
    "volume_in_usd": "604.31", "volume_out_usd": "12.05",
    "distinct_payers": 311, "confidence_basis": "confirmed+probable"
  },
  "meta": { "computed_at": "…", "cache_age_seconds": 312, "api_version": "v1", "disclaimer": "…" }
}

The response schema is a stable contract: fields are only ever added, and a rename or removal means a new API version. Published as JSON Schema alongside the API.

get_service_stats — free

No input. Public counters of the index: addresses indexed, transfers ingested, scores served.

Configuration

Variable

Default

Meaning

API_BASE_URL

https://walletbureau.com

Where the service lives. Change it only to point at your own deployment.

WALLETBUREAU_API_KEY

—

Prepaid API key, atk_….

X402_PRIVATE_KEY

—

Private key that pays per call over x402.

X402_MAX_PRICE_USD

0.10

Hard cap on the price of a single paid call.

REQUEST_TIMEOUT_MS

5000

Timeout for an unpaid request to the service.

PAYMENT_TIMEOUT_MS

60000

Budget for a paid call, including signing and on-chain settlement.

The server logs to stderr only — stdout belongs to the MCP protocol.

What this server does not do

No scoring logic and no data of its own: it is a thin wrapper over the public HTTP API, so a fix to the methodology reaches you without a package upgrade. No local cache either — the service caches, and a second copy would only drift from it.

License

Apache-2.0

Available Tools

2 tools
check_counterpartyCheck counterparty wallet riskA
Read-onlyIdempotent

Before paying an unknown wallet on Base/x402, check its behavioral risk score. Returns 0–100 score, verdict (ok/caution/avoid) and explained risk flags based on the full history of x402/EIP-3009 USDC transfers. Not an accusation — risk signals with reasons. Cost: $0.05 per call, debited from the prepaid API key configured in this server.

ParametersJSON Schema
NameRequiredDescriptionDefault
addressYesWallet address on Base to check: 0x followed by 40 hexadecimal characters.

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Even though annotations already indicate read-only, idempotent, and open-world behavior, the description adds valuable context: the scoring basis (full history of x402/EIP-3009 USDC transfers), the explanatory stance ('Not an accusation — risk signals with reasons'), and the exact cost ($0.05 per call debited from the prepaid API key). This goes well beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences long and every clause earns its place: usage trigger, output summary, data basis, qualitative caveat, and pricing. It is front-loaded with the most actionable information and has zero filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter, read-only tool with no output schema, the description is complete: it explains what happens, what is returned, how it is computed, and what it costs. There is no missing context that would prevent an agent from invoking this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already fully documents the only parameter (address) with format details, so the description does not add much parameter-level meaning. The description gives context ('unknown wallet on Base/x402') but no additional syntactic or semantic information beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('check') and resource ('counterparty wallet risk'/'behavioral risk score'), and clearly distinguishes this from the sibling get_service_stats by focusing on per-wallet risk assessment on Base/x402. It even details the output (0–100 score, verdict, risk flags), so there is no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly identifies when to use the tool ('Before paying an unknown wallet on Base/x402'), which is a strong usage trigger. It does not mention when not to use it or explicitly reference alternatives, but the sibling tool is clearly a different concern, and the cost disclosure further aids decision-making.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_service_statsWalletBureau service statsA
Read-onlyIdempotent

Public counters of the WalletBureau index: addresses indexed, USDC transfers ingested and scores served. Free, no payment required.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds valuable context that the data is publicly accessible at no cost, which is not directly captured by the annotations. It also enumerates the type of counters returned, providing behavioral transparency about the resource.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, front-loaded with the core purpose, and lists concrete examples. Every word contributes value: 'Public counters', specific counter names, and the free-of-charge note. No fluff, perfectly sized for a zero-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple zero-parameter public stats tool, the description is nearly complete: it identifies the resource, examples of return data, and access cost. However, it does not specify whether the counters are cumulative totals, time-windowed, or how frequently they update. This minor ambiguity keeps it from a 5, but given low complexity and the annotations, it is still very complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so parameter semantics are not applicable. Per the guidelines, the baseline for 0 params is 4. The description does not need to explain parameters, but it does clarify what the returned counters represent, which indirectly aids interpretation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves public counters of the WalletBureau index, listing specific data points (addresses indexed, USDC transfers ingested, scores served). This distinguishes it from the sibling tool check_counterparty, which presumably checks a single counterparty. The verb 'get' and noun 'service stats' are explicit and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description notes the tool is 'Public' and 'Free, no payment required', which clearly implies it can be used without authentication or payment. It does not explicitly mention when to use this over check_counterparty, but the sibling's purpose is obviously different (checking a specific counterparty vs getting overall stats). The context is clear enough for an agent to select it appropriately.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedcheck_counterparty
    • First observedget_service_stats
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 2 tools

Disambiguation5/5

The two tools are completely distinct: one provides risk assessments for counterparties, the other returns public service statistics. There is no conceptual overlap, so an agent can easily select the right tool.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern: check_counterparty and get_service_stats. The naming is uniform, clear, and predictable.

Tool Count3/5

With only 2 tools, the server feels thin for a service that likely has a broader range of potential operations (e.g., batch checks, detailed history, dispute reporting). The count is borderline for the stated purpose.

Completeness4/5

The core functionality (checking a counterparty risk score) is fully covered, and the stats tool adds useful supplementary context. Minor gaps exist such as no bulk-check or detailed transaction history, but the primary workflow is complete.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • revettr

    AlexanderLawson17
    A
    license
    A
    quality
    F
    maintenance
    Counterparty risk scoring for agentic commerce. Scores wallets, domains, IPs, and companies 0-100 before AI agents transact via x402 micropayments on Base
    1
    3
    MIT

  • defi-yield-scanner-mcp

    34t34f3
    A
    license
    A
    quality
    D
    maintenance
    Real-time DeFi analytics MCP server for AI agents. Provides token risk analysis, yield scanning, and wallet exposure checking across Base, Ethereum, and Arbitrum.
    3
    7 npm
    1
    MIT

  • pay-mcp

    MonadWorks
    A
    license
    A
    quality
    D
    maintenance
    An MCP server for USDC payments on Base, enabling AI agents to check balances, send payments, generate payment requests, and view transaction history.
    4
    1
    MIT