Metadata-Version: 2.4
Name: nephyr-wallets
Version: 0.1.0
Summary: Smart money tracking for prediction markets — discover, score, and analyze top wallets
Author-email: CLM Studios <citlali.lopmonster.studios@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/clm-studios/nephyr-wallets
Project-URL: Repository, https://github.com/clm-studios/nephyr-wallets
Project-URL: Issues, https://github.com/clm-studios/nephyr-wallets/issues
Keywords: prediction-markets,polymarket,wallet-tracking,smart-money,trading,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: api
Requires-Dist: fastapi>=0.110; extra == "api"
Requires-Dist: uvicorn[standard]>=0.29; extra == "api"
Requires-Dist: pydantic>=2.0; extra == "api"
Requires-Dist: slowapi>=0.1.9; extra == "api"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-httpx>=0.30; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Provides-Extra: all
Requires-Dist: mcp>=1.0; extra == "all"
Requires-Dist: fastapi>=0.110; extra == "all"
Requires-Dist: uvicorn[standard]>=0.29; extra == "all"
Requires-Dist: pydantic>=2.0; extra == "all"
Requires-Dist: slowapi>=0.1.9; extra == "all"
Dynamic: license-file

# Nephyr Wallets

Smart money tracking for prediction markets. Discover, score, and analyze top Polymarket wallets.

## Install

```bash
pip install nephyr-wallets
# With all extras:
pip install "nephyr-wallets[all]"
```

## Quick Start

```python
import asyncio
from nephyr_wallets import get_top_wallets, analyze_wallet, compare_wallets

async def main():
    # Get top 50 wallets
    wallets = await get_top_wallets(limit=50, window="all")

    # Deep analysis of a specific wallet
    analysis = await analyze_wallet("0x...")
    print(analysis.score.total_score)
    print(analysis.category_performance)
    print(analysis.monthly_returns)

    # Compare multiple wallets
    comparison = await compare_wallets(["0x...", "0x..."])

asyncio.run(main())
```

## Scoring Formula

`S(w) = α·log10(1 + PnL/1000) + β·(1 - CoV) + γ·(1 - entropy/log2(6)) − δ·max_drawdown`

Default weights: α=0.4 (PnL), β=0.3 (consistency), γ=0.2 (specialization), δ=0.1 (drawdown penalty)

## REST API

```bash
uvicorn api.app:app --reload
```

Endpoints:
- `GET /v1/leaderboard` — top wallets
- `GET /v1/wallet/{address}/score` — wallet score
- `GET /v1/wallet/{address}/analysis` — deep analysis
- `GET /v1/wallet/{address}/trades` — trade history
- `POST /v1/compare` — compare multiple wallets
- `GET /v1/health` — health check

## MCP Server

```bash
nephyr-wallets-mcp
```

Tools: `get_top_wallets`, `score_wallet`, `analyze_wallet`, `get_wallet_trades`, `compare_wallets`

## Pricing

| Tier | Details |
|------|---------|
| **Free** | Top 10 wallets, delayed 1 hour, 50 calls/day |
| **Paid** | $29/month — real-time, 50 wallets, unlimited calls |
| **Agent-to-agent** | $0.01/query |
