{
  "markdown": "# WalletLens API\n\nPaid 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.\n\n## Secret Setup\n\nDo not paste API keys into chat or commit them. Create a local `.env` from `.env.example`:\n\n```bash\ncp .env.example .env\n```\n\nThen fill in:\n\n```bash\nALCHEMY_API_KEY=your_alchemy_key\nMY_WALLET_ADDRESS=0xYourReceivingWallet\nX402_DEV_BYPASS=true\n```\n\nUse `X402_DEV_BYPASS=true` locally. The AWS deployment defaults to `false` unless you override it.\n\n## Local Development\n\n```bash\nnpm run dev\n```\n\nHealth check:\n\n```bash\ncurl http://localhost:3000/health\n```\n\nFree cached live preview:\n\n```bash\ncurl http://localhost:3000/preview\n```\n\nFree Robinhood Stock Token proof:\n\n```bash\ncurl http://localhost:3000/preview/robinhood\n```\n\nFree paid-call quote:\n\n```bash\ncurl \"http://localhost:3000/quote?address=0x0000000000000000000000000000000000000000&chains=base\"\n```\n\nPortfolio request:\n\n```bash\ncurl \"http://localhost:3000/portfolio?address=0x0000000000000000000000000000000000000000&chains=base,ethereum\"\n```\n\nTxLens history request:\n\n```bash\ncurl \"http://localhost:3000/tx-history?address=0x0000000000000000000000000000000000000000&chains=base&limit=20\"\n```\n\nBundled wallet report request:\n\n```bash\ncurl \"http://localhost:3000/wallet-report?address=0x0000000000000000000000000000000000000000&chains=base&limit=20\"\n```\n\nRobinhood Stock Token report:\n\n```bash\ncurl \"http://localhost:3000/wallet-report?address=0xfac1d7dC76bE90C5Cadd5B022af7838dd8190F16&chains=robinhood&limit=20\"\n```\n\nDiscovery:\n\n```bash\ncurl http://localhost:3000/.well-known/x402.json\n```\n\nVerify that production returns Bazaar metadata and is indexed by Coinbase's\nmerchant and semantic discovery APIs:\n\n```bash\nnpm run check:discovery\n```\n\n## Paid x402 Test\n\nUse a dedicated test wallet. Do not use a high-value wallet or commit the private key.\n\nAdd this to `.env`:\n\n```bash\nX402_TEST_PRIVATE_KEY=0x...\nX402_TEST_ENDPOINT=portfolio\nX402_TEST_BASE_URL=https://walletlens.wallyweb.com\nX402_TEST_ADDRESS=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\nX402_TEST_CHAINS=base,ethereum\nX402_TEST_LIMIT=20\nX402_TEST_DAYS=30\nX402_TEST_CATEGORY=all\n```\n\nThe payer wallet needs Base USDC for the `$0.02` x402 payment.\n\nRun:\n\n```bash\nnpm run test:x402\n```\n\nRun a TxLens paid test:\n\n```bash\nnpm run test:x402 -- --endpoint tx-history --address 0x52E29e0d2Aa49bfBfC548C0A9F2196F4aa51f3ea --chains base --limit 20\n```\n\nRun a bundled wallet report paid test:\n\n```bash\nnpm run test:x402 -- --endpoint wallet-report --address 0x52E29e0d2Aa49bfBfC548C0A9F2196F4aa51f3ea --chains base --limit 20\n```\n\n## Analytics\n\nWalletLens 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.\n\nSummarize recent production usage:\n\n```bash\nnpm run analytics:recent -- --hours 24\n```\n\nOptional flags:\n\n```bash\nnpm run analytics:recent -- --hours 168 --profile wallyweb --region us-east-2\n```\n\n## MCP Server\n\nWalletLens publishes a local stdio MCP server for Codex, Claude Desktop, Cursor,\nand other MCP-compatible agent clients:\n\n```text\nhttps://www.npmjs.com/package/@shawnwollenberg/walletlens-mcp\n```\n\nRun the published package without cloning this repository:\n\n```bash\nnpx --yes @shawnwollenberg/walletlens-mcp@0.1.2\n```\n\nRepository contributors can run the same server from source with `npm run mcp`.\nFree discovery tools require no wallet. For paid calls, set a dedicated,\nlow-balance agent wallet in the MCP server environment:\n\n```bash\nWALLETLENS_X402_PRIVATE_KEY=0x...\n```\n\nThe MCP client defaults to a maximum payment of `$0.02` and accepts only exact\nBase-mainnet USDC requirements for the requested WalletLens endpoint. It also\npins the live WalletLens recipient by default:\n\n```bash\nWALLETLENS_MAX_PAYMENT_USDC=0.02\nWALLETLENS_EXPECTED_PAY_TO=0xA7c82E9775A9594c673E3Fde8a42D3D17dE2B957\nWALLETLENS_REQUEST_TIMEOUT_MS=20000\n```\n\nExample MCP client configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"walletlens\": {\n      \"command\": \"npx\",\n      \"args\": [\"--yes\", \"@shawnwollenberg/walletlens-mcp@0.1.2\"],\n      \"env\": {\n        \"WALLETLENS_X402_PRIVATE_KEY\": \"0xYOUR_DEDICATED_AGENT_PRIVATE_KEY\",\n        \"WALLETLENS_MAX_PAYMENT_USDC\": \"0.02\",\n        \"WALLETLENS_EXPECTED_PAY_TO\": \"0xA7c82E9775A9594c673E3Fde8a42D3D17dE2B957\"\n      }\n    }\n  }\n}\n```\n\nAvailable tools:\n\n- `get_service_metadata`\n- `get_supported_chains`\n- `get_openapi_schema`\n- `get_portfolio`\n- `get_tx_history`\n- `get_wallet_report`\n\n## AWS Deployment\n\nThis project deploys an AWS Lambda Function URL with CDK. It uses the `wallyweb` AWS profile by default in the npm script.\n\nSet `.env` for production before deploying:\n\n```bash\nALCHEMY_API_KEY=your_alchemy_key\nMY_WALLET_ADDRESS=0xYourReceivingWallet\nX402_DEV_BYPASS=false\nX402_PRICE_USD=0.02\nX402_NETWORK=eip155:8453\nX402_FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402\nCDP_API_KEY_ID=your_cdp_key_id\nCDP_API_KEY_SECRET=your_cdp_key_secret\nROOT_DOMAIN=wallyweb.com\nCUSTOM_DOMAIN=walletlens.wallyweb.com\nPUBLIC_BASE_URL=https://walletlens.wallyweb.com\nANALYTICS_IP_SALT=random-long-string\nPROVIDER_TIMEOUT_MS=10000\n```\n\nBootstrap CDK once per account/region if needed:\n\n```bash\nnpm run cdk -- bootstrap --profile wallyweb\n```\n\nDeploy:\n\n```bash\nnpm run deploy:aws\n```\n\nThe deploy output includes `PortfolioApiUrl`. Use that base URL for:\n\n- `GET /health`\n- `GET /status`\n- `GET /preview`\n- `GET /preview/robinhood`\n- `GET /quote?address=...&chains=base`\n- `GET /pricing`\n- `GET /examples`\n- `GET /.well-known/x402.json`\n- `GET /v2/x402/discovery/resources`\n- `GET /.well-known/api-catalog`\n- `GET /portfolio?address=...&chains=base,ethereum`\n- `GET /tx-history?address=...&chains=base&limit=20`\n- `GET /wallet-report?address=...&chains=base&limit=20`\n\nThe public production URL is:\n\n```text\nhttps://walletlens.wallyweb.com\n```\n\n## Supported Chains\n\nInitial EVM support:\n\n- `base`\n- `ethereum` or `eth`\n- `optimism`\n- `arbitrum`\n- `polygon`\n- `robinhood` or `robinhood-chain` (Robinhood Chain mainnet, `eip155:4663`)\n\nRobinhood 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.\n\nSolana is intentionally out of scope for the first version.\n",
  "bytes": 6878,
  "sha": "a4f5b7e614f20679ca6338e1328fe9c7b1b543fa2be42bd06e03555877fbd9f6",
  "repo_slug": "shawnwollenberg/web3_portfolio",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_shawnwollenberg_walletlens_62d2e1e2/readme"
}