Metadata-Version: 2.4
Name: hyper-sentinel
Version: 0.4.0
Summary: Python SDK + AI Agent for Sentinel — 80+ crypto trading, AI, and market intelligence tools with interactive chat. Free access, usage-based fees.
Author-email: Sentinel Labs <dev@hyper-sentinel.com>
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://hyper-sentinel.com
Project-URL: Documentation, https://hyper-sentinel.com/docs
Project-URL: Repository, https://github.com/hyper-sentinel/hyper-sentinel-sdk
Project-URL: Issues, https://github.com/hyper-sentinel/hyper-sentinel-sdk/issues
Keywords: crypto,trading,ai,defi,hyperliquid,aster,polymarket,sentinel,agent
Classifier: Development Status :: 4 - Beta
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 :: Investment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Requires-Dist: rich>=13.0
Requires-Dist: requests>=2.31.0
Requires-Dist: yfinance>=0.2.0
Requires-Dist: tenacity>=8.0
Requires-Dist: py-clob-client>=0.17.0
Requires-Dist: eth-account>=0.11.0
Provides-Extra: serve
Requires-Dist: fastapi>=0.111.0; extra == "serve"
Requires-Dist: uvicorn[standard]>=0.29.0; extra == "serve"
Provides-Extra: swarm
Requires-Dist: upsonic>=0.30.0; extra == "swarm"
Provides-Extra: telegram
Requires-Dist: telethon>=1.36.0; extra == "telegram"
Provides-Extra: async
Requires-Dist: httpx[http2]; extra == "async"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

<div align="center">
<br/>

```
██╗  ██╗██╗   ██╗██████╗ ███████╗██████╗
██║  ██║╚██╗ ██╔╝██╔══██╗██╔════╝██╔══██╗
███████║ ╚████╔╝ ██████╔╝█████╗  ██████╔╝
██╔══██║  ╚██╔╝  ██╔═══╝ ██╔══╝  ██╔══██╗
██║  ██║   ██║   ██║     ███████╗██║  ██║
╚═╝  ╚═╝   ╚═╝   ╚═╝     ╚══════╝╚═╝  ╚═╝
```

# Hyper-Sentinel

**Quantitative AI Agent — Crypto, TradFi, Equities & Macro**

60+ tools · 12 data sources · Multi-agent swarm · SaaS API

<br/>

[![PyPI](https://img.shields.io/pypi/v/hyper-sentinel?style=flat&logo=pypi&logoColor=white&label=pypi&color=00e5ff)](https://pypi.org/project/hyper-sentinel/)
[![Python](https://img.shields.io/pypi/pyversions/hyper-sentinel?style=flat&logo=python&logoColor=white&color=00e5ff)](https://pypi.org/project/hyper-sentinel/)
[![License](https://img.shields.io/github/license/hyper-sentinel/hyper-sentinel-sdk?style=flat&color=00e5ff)](LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/hyper-sentinel?style=flat&logo=pypi&logoColor=white&label=downloads&color=00e5ff)](https://pypi.org/project/hyper-sentinel/)

[Website](https://hyper-sentinel.com) · [REST API](https://github.com/hyper-sentinel/docs/blob/main/rest-api/README.md) · [PyPI](https://pypi.org/project/hyper-sentinel/)

</div>

---

## Install

```bash
pip install hyper-sentinel
```

## Two Ways to Use It

### 1. Python SDK — Call the API directly

```python
from sentinel.api import SentinelAPI

client = SentinelAPI(api_key="sk-sentinel-xxx")

# Market data
btc = client.market.price("bitcoin")
top = client.market.top_crypto(10)
macro = client.market.dashboard()

# AI chat (metered per your tier)
response = client.chat.send("analyze BTC outlook")

# Streaming
for chunk in client.chat.send("deep dive NVDA", stream=True):
    print(chunk["text"], end="", flush=True)

# Trading (⚠️ real money)
positions = client.trade.hl_positions()
client.trade.hl_order(coin="ETH", side="buy", size=0.5)

# Aster DEX
client.trade.aster_order(symbol="BTCUSDT", side="buy", size=0.01)

# Polymarket
markets = client.trade.pm_markets()
client.trade.pm_buy(token_id="...", amount=10, price=0.65)

# Billing & usage
client.billing.status()
client.billing.breakdown()

# Key management
client.keys.list()
client.keys.create("my-bot")
client.keys.revoke("key_abc123")

# Any of the 60+ tools
client.tools.call("get_fred_series", series_id="GDP")
```

### 2. Interactive Agent — Chat in your terminal

```bash
sentinel
```

Paste your AI key. Ask anything. The agent has all 60+ tools.

```
  ⚡ You → price of btc and eth

  ╭───────────────────────── 🛡️ Sentinel ──╮
  │                                          │
  │  Bitcoin (BTC): $66,839.00               │
  │    24h: -0.42%  ·  7d: +1.8%            │
  │                                          │
  │  Ethereum (ETH): $1,812.40               │
  │    24h: +0.21%  ·  7d: -2.1%            │
  │                                          │
  ╰────────────────────── ⚡ instant ────────╯
```

---

## How It Works

Every SDK call routes through the Sentinel API gateway on Google Cloud Run. The gateway handles authentication, rate limiting, and fee capture.

```
pip install hyper-sentinel
         │
         ▼
┌────────────────────────────┐
│  Go API Gateway            │
│  Auth · Billing · Metering │
│  Cloud Run · us-central1   │
└────────────┬───────────────┘
             │
┌────────────▼───────────────┐
│  Python Runtime (FastAPI)  │
│  60+ tools · 12 scrapers  │
│  HL · Aster · PM · FRED   │
└────────────────────────────┘
```

---

## Data Sources

| Source | What You Get | Setup |
|:-------|:-------------|:------|
| 🪙 **CoinGecko** | 10,000+ coins · prices · market data | None |
| 📈 **YFinance** | Stocks · ETFs · analyst recs · financials | None |
| 📊 **DexScreener** | DEX pairs · trending tokens · new listings | None |
| 📉 **Technical Analysis** | SMA · EMA · RSI · MACD · Bollinger Bands | None |
| ⚡ **Hyperliquid** | Perps · positions · orders · TradFi | `add hl` |
| 🌟 **Aster DEX** | Futures · positions · klines · leverage | `add aster` |
| 🎲 **Polymarket** | Prediction markets · positions · buy/sell | `add polymarket` |
| 🏛️ **FRED** | GDP · CPI · rates · 800K+ economic series | `add fred` |
| 📰 **Y2 Intelligence** | News sentiment · intelligence reports | `add y2` |
| 🔮 **Elfa AI** | Trending tokens · social mentions | `add elfa` |
| 🐦 **X / Twitter** | Tweet search · accounts · trends | `add x` |

---

## Pricing

No feature gating. Everyone gets full access. Subscriptions reduce your fees.

| Tier | Price | LLM Markup | Trade Fee | Rate Limit |
|------|-------|-----------|-----------|-----------|
| **Free** | $0 | 40% | 0.10% / 0.07% | 300/min |
| **Pro** | $100/mo | 20% | 0.06% / 0.04% | 1,000/min |
| **Enterprise** | $1,000/mo | 10% | 0.02% / 0.01% | Unlimited |

```python
client.billing.subscribe("pro")  # → Stripe checkout URL
```

---

## LLM Providers

| Provider | Prefix | Link |
|:---------|:-------|:-----|
| Anthropic (Claude) | `sk-ant-` | [console.anthropic.com](https://console.anthropic.com) |
| OpenAI (GPT) | `sk-` | [platform.openai.com](https://platform.openai.com) |
| Google (Gemini) | `AIza` | [aistudio.google.com](https://aistudio.google.com) |
| xAI (Grok) | `xai-` | [console.x.ai](https://console.x.ai) |

---

## Changelog

### v0.3.17 — SDK ↔ Gateway Full Sync

- **NEW**: `client.keys` — list, create, revoke API keys from code
- **NEW**: `client.billing.breakdown()` — per-tool, per-day usage stats
- **NEW**: `client.docs()` — pull OpenAPI spec programmatically
- **FIX**: Base URL pointed to current Cloud Run revision
- SDK now maps 1:1 to every Go gateway endpoint

### v0.3.16 — SaaS API Client

- **NEW**: `SentinelAPI` client with typed resources (market, chat, trade, billing, tools)
- **NEW**: SSE streaming for LLM chat (`client.chat.send(stream=True)`)
- **NEW**: RFC 7807 error mapping to typed exceptions
- **NEW**: `sentinel.api.auth` — programmatic registration and AI-key auth

### v0.3.14 — TradFi Integration + Technical Analysis

> *Soli Deo Gloria*

- **NEW**: TradFi perp trading — GOLD, SILVER, OIL, TSLA, NVDA + 50 more via Hyperliquid
- **NEW**: Technical Analysis engine — SMA, EMA, RSI(14), MACD, Bollinger Bands
- **NEW**: DexScreener tools — search, trending, token profiles
- **TOTAL**: 60+ tools · 12 scrapers · 3 trading venues

---

## Links

- [REST API Reference](https://github.com/hyper-sentinel/docs/blob/main/rest-api/README.md)
- [Postman Collection](https://github.com/hyper-sentinel/hyper-sentinel-go/blob/main/Sentinel_API.postman_collection.json)
- [GitHub](https://github.com/hyper-sentinel/hyper-sentinel-sdk)

## License

[AGPL-3.0](LICENSE) — © 2026 Sentinel Labs

---

<div align="center">
<sub><i>Soli Deo Gloria</i> — To the Glory of God alone.</sub>
</div>
