Metadata-Version: 2.4
Name: wallet-doctor
Version: 0.2.3
Summary: Solana blockchain forensics SDK for AI agents. Pay-per-call in SOL/USDC, no API keys, x402 v2 compliant. 13 services from $0.001 per call.
Author-email: Wallet Doctor <wallet-doctor@smartlivingcircle-lab.org>
License: MIT
Project-URL: Homepage, https://wallet-doctor-agents.pages.dev
Project-URL: Repository, https://github.com/zikriz/wallet-doctor-sdk
Project-URL: Documentation, https://github.com/zikriz/wallet-doctor-sdk/blob/main/README.md
Project-URL: Bug Tracker, https://github.com/zikriz/wallet-doctor-sdk/issues
Project-URL: MCP Registry, https://registry.modelcontextprotocol.io/v0/servers/io.github.zikriz/wallet-doctor
Keywords: solana,blockchain,forensics,ai-agents,x402,model-context-protocol,mcp,wallet,wallet-doctor,tracer,scam-detection,drain-analysis,smart-money,ai,rag,nft-audit,portfolio-audit,token-safety
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Framework :: AsyncIO
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Requires-Dist: httpx>=0.27; extra == "mcp"
Provides-Extra: registry
Requires-Dist: requests>=2.31; extra == "registry"
Provides-Extra: bazaar
Requires-Dist: requests>=2.31; extra == "bazaar"
Requires-Dist: httpx>=0.27; extra == "bazaar"

<!-- mcp-name: io.github.zikriz/wallet-doctor -->

<div align="center">

# Wallet Doctor — Solana Forensics for AI Agents

[![PyPI](https://img.shields.io/pypi/v/wallet-doctor)](https://pypi.org/project/wallet-doctor/)
[![MCP Registry](https://img.shields.io/badge/MCP-registry%20active-brightgreen)](https://registry.modelcontextprotocol.io)
[![Solana](https://img.shields.io/badge/solana-mainnet-9945FF)](https://solana.com)
[![License](https://img.shields.io/badge/license-MIT-blue)]()
[![Telegram](https://img.shields.io/badge/telegram-@DoctorWalletScanner__bot-blue)](https://t.me/DoctorWalletScanner_bot)

**Give your AI agent wallet superpowers.** Check balances, trace transactions, detect drain
attacks, audit token safety, identify smart money — pay-per-call in SOL, no API keys, no accounts.

```bash
pip install wallet-doctor
```

</div>

---

## Why Wallet Doctor?

- **For AI agents** — 13 services, all pay-per-call. Every check is one HTTP call.
- **For Solana data** — Real-time on-chain reads via Helius + DexScreener.
- **For threat detection** — Drain forensics, rug analysis, approvals audit, scam labels.
- **For trading bots** — Token safety, liquidity, smart money flow — all before you trade.
- **Pricing** — From **0.001 SOL** (~$0.07) per call. No subscriptions.
- **Payment** — Just send SOL, return tx hash. **No API keys, no signup.**

```python
from wallet_doctor import WalletDoctor

wd = WalletDoctor()

safety = wd.token_safety(wallet="8xHUrNy3ZGwmqG5o2TGMrLDNTVjVwweUxDWLrL9SAD6")
if not safety.get("is_safe"):
    print("Unsafe token detected, refusing to trade")

result = wd.txtrace(wallet="victim...", tx="4Zk2...")
result = wd.portfolio_audit(wallet="...")
```

## All 13 Services

| Service | Price (SOL) | Description |
|---|---|---|
| `balance` | 0.001 | SOL + SPL token balances |
| `price_oracle` | 0.001 | DEX price for any SPL token |
| `token_safety` | 0.005 | Honeypot, mint/freeze authority check |
| `wallet_labels` | 0.005 | Scam/honeypot protocol interactions |
| `approvals` | 0.005 | All active token approvals on a wallet |
| `txtrace` | 0.005 | Last 20 transaction signatures |
| `nft_audit` | 0.005 | NFT holdings with metadata |
| `token_holders` | 0.010 | Top 10 holders + % supply |
| `smart_money` | 0.010 | Whale/smart-money detection |
| `liquidity_check` | 0.015 | LP pool size + lock status |
| `launch_analysis` | 0.020 | New token launch (rug-risk) |
| `drain_forensics` | 0.025 | Full drain attack analysis |
| `portfolio_audit` | 0.025 | Complete wallet security audit |

## How Payment Works

Send SOL with any wallet, post the tx hash, get the data:

```bash
solana transfer --recipient 4dX3VmkGFJHj1XZbWN1MbRYnCaxYWEEN21LjkmCe9JRE 0.001 --allow-unfunded-recipient
```

```bash
curl 'https://defi-webhook.m-zikriz.workers.dev/api/agent?service=balance&wallet=<addr>&tx=<your_tx_hash>'
```

The worker verifies your payment on-chain instantly (sub-second).

## Plug into any agent framework

```json
{"mcpServers":{"wallet-doctor":{"url":"https://defi-webhook.m-zikriz.workers.dev"}}}
```

Compatible with: Claude Code, Cursor, Windsurf, ChatGPT Actions, Gemini, AWS AgentCore,
CrewAI, LangChain, AutoGPT, n8n, MCP Inspector.

## Quick Start (Python)

```bash
pip install wallet-doctor
```

```python
from wallet_doctor import WalletDoctor
wd = WalletDoctor()
print(wd.balance(wallet="<addr>"))  # tx_hash required if SOL not pre-paid
```

## Quick Start (CLI)

```bash
wallet-doctor balance --wallet <addr> --tx <tx_hash>
wallet-doctor token_safety --wallet <addr> --tx <tx_hash>
```

## Quick Start (HTTP)

```bash
curl 'https://defi-webhook.m-zikriz.workers.dev/api/agent?service=balance&wallet=<addr>&tx=<tx_hash>'
```

## Discovery Endpoints

| Channel | URL |
|---|---|
| MCP Official Registry | https://registry.modelcontextprotocol.io/v0/servers/io.github.zikriz/wallet-doctor |
| PyPI | https://pypi.org/project/wallet-doctor/ |
| NPM (MCP server) | https://www.npmjs.com/package/wallet-doctor-mcp |
| GitHub | https://github.com/zikriz/wallet-doctor-mcp |
| Agent Manifest | https://wallet-doctor-agents.pages.dev/agent.json |

## Compatibility

Solana mainnet · Helius RPC · Metaplex NFT · Jupiter / Raydium DEX · x402 protocol · MCP 2025-06-18

## License

MIT — Wallet Doctor
