Metadata-Version: 2.4
Name: optiview-cli
Version: 1.1.0
Summary: OptiView DeFi CLI — swap, portfolio, yield scouting & composite ranking, and EVM wallet management in one command.
License: MIT
Project-URL: Homepage, https://github.com/OptiView-official/optiview-skill
Project-URL: Repository, https://github.com/OptiView-official/optiview-skill
Project-URL: Bug Tracker, https://github.com/OptiView-official/optiview-skill/issues
Keywords: defi,swap,evm,wallet,yields,portfolio,cli,web3,0x,debank,defillama,ranking
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Provides-Extra: rank
Requires-Dist: numpy>=1.24.0; extra == "rank"
Requires-Dist: pandas>=2.0.0; extra == "rank"
Provides-Extra: wallet
Requires-Dist: web3>=6.0.0; extra == "wallet"
Requires-Dist: eth-account>=0.9.0; extra == "wallet"
Provides-Extra: all
Requires-Dist: numpy>=1.24.0; extra == "all"
Requires-Dist: pandas>=2.0.0; extra == "all"
Requires-Dist: web3>=6.0.0; extra == "all"
Requires-Dist: eth-account>=0.9.0; extra == "all"

# optiview-cli

> Plug-and-play DeFi agent skills for OptiView — letting any LLM agent swap tokens, manage portfolios, scout stablecoin yields, rank yield pools by composite score, and control EVM wallets through a single `optiview` CLI, no API wiring required.

[![PyPI](https://img.shields.io/pypi/v/optiview-cli)](https://pypi.org/project/optiview-cli/)
[![Python](https://img.shields.io/pypi/pyversions/optiview-cli)](https://pypi.org/project/optiview-cli/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## Skills

| Skill | Description | Auth Required |
|---|---|---|
| `swap` | Token swap via 0x Protocol: price quotes, full quotes with calldata, supported chains and token lists | No |
| `assets` | Portfolio management via DeBank: total balance, per-chain balance, tokens, DeFi positions, NFTs, transaction history, net worth curves | No |
| `yields scout` | Stablecoin yield scouting via DeFiLlama: filter and rank pools by APY, TVL, and chain | No |
| `yields rank` | Multi-dimensional yield pool ranking: composite score across TVL depth, APY sustainability, prediction confidence, and risk | No |
| `wallet` | EVM wallet management: create wallets, query balances, send ETH/ERC-20, sign messages, track transactions | No |

## Requirements

Install the `optiview` CLI:

```shell
pip install optiview-cli
```

For yield ranking (composite scoring), install with the rank extra:

```shell
pip install "optiview-cli[rank]"
```

For wallet operations (send/sign transactions), install with the wallet extra:

```shell
pip install "optiview-cli[wallet]"
```

For everything:

```shell
pip install "optiview-cli[all]"
```

## Quick Start

```shell
export OPTIVIEW_API_URL=https://optiview.app

# Swap: get price for 1000 USDC → WETH on Ethereum
optiview swap price \
  --sell-token 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
  --buy-token  0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
  --sell-amount 1000000000 \
  --chain-id 1

# Portfolio: total USD balance
optiview assets total-balance --address 0xYOUR_ADDRESS

# Yields: scout stablecoin pools (APY-first, chain-grouped)
optiview yields scout --chain Ethereum --output markdown

# Yields: composite ranking across all chains (score-first)
optiview yields rank --limit 20 --output markdown

# Wallet: create a new EVM wallet
optiview wallet new
```

## Yield Ranking

The `yields rank` command scores every pool across four dimensions:

| Dimension | Weight | Description |
|-----------|--------|-------------|
| TVL depth | 37.5% | log10(TVL) with p5–p95 percentile normalisation |
| APY sustainability | 37.5% | Exponential saturation curve; penalises short-term incentive spikes |
| Prediction confidence | 25% | DefiLlama ML signal (binnedConfidence + predictedClass) |
| Risk factor | −25% max | Outlier flag + IL risk level + 7-day APY volatility |

Each pool receives a composite score from 0 to 100. Output fields include `score`, `risk_level` (Low/Medium/High), and `predicted_class` (Stable/Up/Down).

```shell
# Top 50 across all chains (default)
optiview yields rank

# Top 20 on Ethereum, Markdown
optiview yields rank --chain Ethereum --limit 20 --output markdown

# Custom TVL threshold, JSON
optiview yields rank --tvl 5000000 --limit 100 --output json
```

## Python API

```python
import optiview

# Swap
price = optiview.swap_get_price("0xUSDC", "0xWETH", "1000000000", chain_id="1")

# Assets
total = optiview.assets_total_balance("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")

# Yields: simple scout (APY-first, chain-grouped)
ranked = optiview.yields_scout(min_tvl=30_000_000, min_apy=4.0, top_n=10, chain="Ethereum")

# Yields: composite ranking (score-first, cross-chain)  [requires: pip install optiview-cli[rank]]
top_pools = optiview.yields_rank(limit=50, chain=None, min_tvl=1_000_000)
top_eth   = optiview.yields_rank(limit=20, chain="Ethereum", min_tvl=5_000_000)

# Wallet
w = optiview.wallet_create()
bal = optiview.wallet_native_balance("https://eth.llamarpc.com", w["address"])
```

## Changelog

### 1.1.0
- **New**: `yields rank` command — multi-dimensional composite scoring across TVL depth, APY sustainability, DefiLlama prediction confidence, and risk factors
- **New**: `optiview.yields_rank()` Python API
- **New**: `[rank]` optional dependency group (`numpy`, `pandas`)
- No breaking changes; all 1.0.x commands remain unchanged

### 1.0.0
- Initial release: swap, assets, yields scout, wallet

## License

MIT
