Web3 Portfolio 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 X402_DEV_BYPASS=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...

The MCP client defaults to a maximum payment of $0.02 and accepts only exact Base-mainnet USDC requirements for the requested WalletLens endpoint. It also pins the live WalletLens recipient by default:

WALLETLENS_MAX_PAYMENT_USDC=0.02
WALLETLENS_EXPECTED_PAY_TO=0xA7c82E9775A9594c673E3Fde8a42D3D17dE2B957
WALLETLENS_REQUEST_TIMEOUT_MS=20000

Example MCP client configuration:

{
  "mcpServers": {
    "walletlens": {
      "command": "npx",
      "args": ["--yes", "@shawnwollenberg/walletlens-mcp@0.1.2"],
      "env": {
        "WALLETLENS_X402_PRIVATE_KEY": "0xYOUR_DEDICATED_AGENT_PRIVATE_KEY",
        "WALLETLENS_MAX_PAYMENT_USDC": "0.02",
        "WALLETLENS_EXPECTED_PAY_TO": "0xA7c82E9775A9594c673E3Fde8a42D3D17dE2B957"
      }
    }
  }
}

Available tools:

• get_service_metadata
• get_supported_chains
• get_openapi_schema
• get_portfolio
• get_tx_history
• get_wallet_report

AWS Deployment

This project deploys an AWS Lambda Function URL with CDK. It uses the wallyweb AWS profile by default in the npm script.

Set .env for production before deploying:

ALCHEMY_API_KEY=your_alchemy_key
MY_WALLET_ADDRESS=0xYourReceivingWallet
X402_DEV_BYPASS=false
X402_PRICE_USD=0.02
X402_NETWORK=eip155:8453
X402_FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402
CDP_API_KEY_ID=your_cdp_key_id
CDP_API_KEY_SECRET=your_cdp_key_secret
ROOT_DOMAIN=wallyweb.com
CUSTOM_DOMAIN=walletlens.wallyweb.com
PUBLIC_BASE_URL=https://walletlens.wallyweb.com
ANALYTICS_IP_SALT=random-long-string
PROVIDER_TIMEOUT_MS=10000

Bootstrap CDK once per account/region if needed:

npm run cdk -- bootstrap --profile wallyweb

Deploy:

npm run deploy:aws

The deploy output includes PortfolioApiUrl. Use that base URL for:

• GET /health
• GET /status
• GET /preview
• GET /preview/robinhood
• GET /quote?address=...&chains=base
• GET /pricing
• GET /examples
• GET /.well-known/x402.json
• GET /v2/x402/discovery/resources
• GET /.well-known/api-catalog
• GET /portfolio?address=...&chains=base,ethereum
• GET /tx-history?address=...&chains=base&limit=20
• GET /wallet-report?address=...&chains=base&limit=20

The public production URL is:

https://walletlens.wallyweb.com

Supported Chains

Initial EVM support:

• base
• ethereum or eth
• optimism
• arbitrum
• polygon
• robinhood or robinhood-chain (Robinhood Chain mainnet, eip155:4663)

Robinhood Stock Tokens are matched against Robinhood's canonical asset registry. WalletLens reports the current corporate-action multiplier, bid/ask quote, multiplier-adjusted midpoint value, trading-halt status, and available trading capabilities. Canonical Robinhood Chain USDG is valued at its $1 reference price. Base USDC remains the x402 payment asset regardless of the report target chain.

Solana is intentionally out of scope for the first version.