Walletlens MCP server

WalletLens API

Paid API for EVM wallet intelligence: normalized portfolio snapshots, canonical Robinhood Stock Token holdings and prices, bundled wallet reports, and TxLens enriched transaction history. The app uses Alchemy plus Robinhood's public Stock Token APIs, then gates paid endpoints with x402 unless local dev bypass is enabled.

Secret Setup

Do not paste API keys into chat or commit them. Create a local .env from .env.example:

cp .env.example .env

Then fill in:

ALCHEMY_API_KEY=your_alchemy_key
MY_WALLET_ADDRESS=0xYourReceivingWallet
X402_DEV_BYPASS=true

Use X402DEVBYPASS=true locally. The AWS deployment defaults to false unless you override it.

Local Development

npm run dev

Health check:

curl http://localhost:3000/health

Free cached live preview:

curl http://localhost:3000/preview

Free Robinhood Stock Token proof:

curl http://localhost:3000/preview/robinhood

Free paid-call quote:

curl "http://localhost:3000/quote?address=0x0000000000000000000000000000000000000000&chains=base"

Portfolio request:

curl "http://localhost:3000/portfolio?address=0x0000000000000000000000000000000000000000&chains=base,ethereum"

TxLens history request:

curl "http://localhost:3000/tx-history?address=0x0000000000000000000000000000000000000000&chains=base&limit=20"

Bundled wallet report request:

curl "http://localhost:3000/wallet-report?address=0x0000000000000000000000000000000000000000&chains=base&limit=20"

Robinhood Stock Token report:

curl "http://localhost:3000/wallet-report?address=0xfac1d7dC76bE90C5Cadd5B022af7838dd8190F16&chains=robinhood&limit=20"

Discovery:

curl http://localhost:3000/.well-known/x402.json

Verify that production returns Bazaar metadata and is indexed by Coinbase's merchant and semantic discovery APIs:

npm run check:discovery

Paid x402 Test

Use a dedicated test wallet. Do not use a high-value wallet or commit the private key.

Add this to .env:

X402_TEST_PRIVATE_KEY=0x...
X402_TEST_ENDPOINT=portfolio
X402_TEST_BASE_URL=https://walletlens.wallyweb.com
X402_TEST_ADDRESS=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
X402_TEST_CHAINS=base,ethereum
X402_TEST_LIMIT=20
X402_TEST_DAYS=30
X402_TEST_CATEGORY=all

The payer wallet needs Base USDC for the $0.02 x402 payment.

Run:

npm run test:x402

Run a TxLens paid test:

npm run test:x402 -- --endpoint tx-history --address 0x52E29e0d2Aa49bfBfC548C0A9F2196F4aa51f3ea --chains base --limit 20

Run a bundled wallet report paid test:

npm run test:x402 -- --endpoint wallet-report --address 0x52E29e0d2Aa49bfBfC548C0A9F2196F4aa51f3ea --chains base --limit 20

Analytics

WalletLens emits one privacy-conscious JSON analytics event per request to CloudWatch Logs. It records endpoint, status, latency, requested wallet, query parameters, hashed IP, user agent, response counts, and x402 settlement fields when available. It does not log private keys, x402 signatures, raw payment payloads, or full response bodies.

Summarize recent production usage:

npm run analytics:recent -- --hours 24

Optional flags:

npm run analytics:recent -- --hours 168 --profile wallyweb --region us-east-2

MCP Server

WalletLens publishes a local stdio MCP server for Codex, Claude Desktop, Cursor, and other MCP-compatible agent clients:

https://www.npmjs.com/package/@shawnwollenberg/walletlens-mcp

Run the published package without cloning this repository:

npx --yes @shawnwollenberg/walletlens-mcp@0.1.2

Repository contributors can run the same server from source with npm run mcp. Free discovery tools require no wallet. For paid calls, set a dedicated, low-balance agent wallet in the MCP server environment:

WALLETLENS_X402_PRIVATE_KEY=0x...

Shortened. The full README is on GitHub.