Hyper-Sentinel SDK Documentation

Installation

Requires Python 3.10+. Works on Mac, Windows, and Linux.

# pip (Mac / Windows PowerShell / Linux)
pip install hyper-sentinel

# uv (recommended — faster)
uv add hyper-sentinel

# With HTTP/2 support (optional)
pip install hyper-sentinel[async]

Quick Start

# One-time setup — paste your AI key, done
$ pip install hyper-sentinel
$ sentinel-setup

from sentinel import SentinelClient

# After setup, zero arguments — keys auto-loaded from ~/.sentinel/config
client = SentinelClient()

# Market data
btc = client.get_crypto_price("bitcoin")
top = client.get_crypto_top_n(10)
aapl = client.get_stock_price("AAPL")

# AI chat (proxied through Sentinel — tier markup applies)
resp = client.chat("Analyze BTC market structure")

# Trade on Hyperliquid
client.place_hl_order(coin="ETH", side="buy", size=0.1)

# DEX swaps
client.dex_buy_sol(contract_address="So1...", amount_sol=0.5)

Authentication — Web4

No email. No password. Your AI provider key is your identity.

# Option 1: Interactive setup (recommended — run once)
$ sentinel-setup

# Option 2: Pass AI key directly in code
client = SentinelClient(ai_key="sk-ant-xxx")

# After setup, zero arguments needed
client = SentinelClient()  # auto-loads from ~/.sentinel/config

Supported providers:

Anthropic (Claude)sk-ant-xxx → console.anthropic.com

OpenAI (GPT)sk-xxx → platform.openai.com

Google (Gemini)AIza... → aistudio.google.com

xAI (Grok)xai-xxx → console.x.ai

How Auth Works

When you paste your AI key, the SDK auto-creates a Sentinel account:

Your AI key is hashed (SHA-256) → deterministic user ID
Gateway generates a sk-sentinel-xxx platform key
Saved to ~/.sentinel/config (0600 permissions)
Your AI key is never stored on the server
All future API calls use your Sentinel key transparently

Zero Friction
One command. Paste your key. Start building. No signup form, no email verification, no password.

Pricing Tiers

All 80+ tools are available on every tier. Upgrading reduces fees and increases rate limits:

Tier	Price	LLM Markup	Maker Fee	Taker Fee	Rate Limit
Free	$0/mo	40%	0.10%	0.08%	300/min
Pro	$100/mo	20%	0.06%	0.04%	1,000/min
Enterprise	$1,000/mo	10%	0.02%	0.01%	Unlimited

# Upgrade via CLI
$ sentinel upgrade
$ sentinel upgrade enterprise

# Check billing
$ sentinel billing

Billing & Usage

billing_status() Current tier, subscription status, and active plan details

billing_usage() Current period usage breakdown by category

billing_history() Past invoices and payment history

AI Chat (Multi-LLM)

Bring your own AI key and query any supported LLM through a single interface:

resp = client.chat(
    prompt="Analyze ETH/BTC ratio",
    ai_key="sk-ant-xxx",         # Your provider key
    model="claude-sonnet-4-20250514", # Optional model override
    provider="anthropic",       # anthropic | openai | google
)
print(resp["response"])

chat(prompt, ai_key, ...) Multi-LLM chat — supports Claude, GPT, Gemini, Grok

llm_usage() LLM call history: tokens used, costs, model breakdown

Crypto Market Data

get_crypto_price(coin_id) Live price, market cap, 24h change for any coin

get_crypto_top_n(n) Top N cryptocurrencies by market cap

search_crypto(query) Search coins by name or symbol

Equities (yfinance)

get_stock_price(symbol) Current stock price and key metrics

get_stock_info(symbol) Company info, sector, market cap, P/E

get_analyst_recs(symbol) Analyst consensus ratings and price targets

get_stock_news(symbol) Recent news articles for a ticker

get_stock_history(symbol, period) Historical OHLCV data (1d, 5d, 1mo, 1y, max)

Macro Economics (FRED)

get_fred_series(series_id, limit) Fetch FRED time series (GDP, CPI, rates, etc.)

search_fred(query) Search FRED database for economic indicators

get_economic_dashboard() Pre-built dashboard: GDP, CPI, unemployment, rates

News & Sentiment

get_news_sentiment(query) Sentiment-analyzed news articles for a topic

get_news_recap() Today's market recap and key headlines

get_intelligence_reports() Curated intelligence reports

get_report_detail(report_id) Full text of a specific intelligence report

Social Intelligence (Elfa AI)

get_trending_tokens() Trending tokens by social mention volume

get_top_mentions() Most mentioned tokens across social platforms

search_mentions(query) Search social mentions for a specific token/topic

get_trending_narratives() Emerging market narratives and themes

get_token_news(token) Aggregated news and social posts for a token

X / Twitter Search

search_x(query, max_results) Search X/Twitter for recent posts matching a query

DexScreener

dexscreener_search(query) Search for token pairs across all DEXs

dexscreener_token(address) Get all pairs for a specific token address

dexscreener_trending() Currently trending pairs on DexScreener

dexscreener_pair(chain, pair) Detailed pair data by chain and pair address

Hyperliquid (Perpetuals)

# Place a leveraged long
client.place_hl_order(
    coin="ETH",
    side="buy",
    size=0.5,
    leverage=5,
    order_type="market",
)

get_hl_config() Exchange configuration and supported assets

get_hl_orderbook(coin) Level-2 order book for a perpetual pair

get_hl_account_info() Account equity, margin, and leverage info

get_hl_positions() Open positions with P&L and liquidation prices

get_hl_open_orders() Pending limit/stop orders

place_hl_order(...) Place market/limit/stop orders with leverage

cancel_hl_order(coin, order_id) Cancel a pending order

close_hl_position(coin) Market-close an open position

Aster DEX (Perpetuals)

aster_ping() Test Aster API connectivity

aster_ticker(symbol) 24h ticker data for a trading pair

aster_orderbook(symbol, limit) Order book depth data

aster_klines(symbol, interval, limit) Candlestick/OHLCV data

aster_funding_rate(symbol) Current funding rate for perpetuals

aster_exchange_info() Supported symbols, limits, and trading rules

aster_diagnose() Diagnose Aster API connectivity issues

aster_balance() Account balances on Aster

aster_positions() Open positions on Aster

aster_account_info() Account details and trading status

aster_place_order(...) Place orders on Aster DEX

DEX Swaps (Solana & Ethereum)

# Buy a Solana memecoin
client.dex_buy_sol(
    contract_address="So1111...mint",
    amount_sol=0.5,
    slippage=5.0,
)

dex_buy_sol(address, amount, slippage) Buy token with SOL on Raydium/Jupiter

dex_sell_sol(address, pct, slippage) Sell token for SOL (percentage-based)

dex_buy_eth(address, amount, slippage) Buy token with ETH on Uniswap

dex_sell_eth(address, pct, slippage) Sell token for ETH (percentage-based)

dex_price_sol(address) Get current price of a Solana token

dex_price_eth(address) Get current price of an Ethereum token

Algo Trading

get_strategy() Get current active strategy configuration

set_strategy(name, params, ...) Configure strategy parameters (algo, symbols, risk)

list_algos() List available algo strategies

start_strategy() Start the active strategy

stop_strategy() Stop the running strategy

Wallet Management

generate_wallet(chain) Generate a new wallet (sol, eth, btc)

import_wallet(chain, key, label) Import existing wallet by private key

list_wallets() List all managed wallets

get_wallet_balance(address, chain) Check native + token balances

send_crypto(to, amount, chain) Send crypto from managed wallet

USDC Billing

usdc_balance() Current USDC credit balance

usdc_deposit_address() Get your Solana deposit address for USDC

usdc_deposits() Deposit history

usdc_register_wallet(address) Register a Solana wallet for deposits

usdc_check_deposits() Manually trigger deposit check

Telegram

tg_get_updates(limit) Poll for latest messages and events

tg_send_message(target, message) Send a message to a chat/group

Discord

discord_read_channel(channel_id, limit) Read recent messages from a channel

discord_search_messages(channel_id, query) Search messages in a channel

discord_list_guilds() List all connected Discord servers

discord_list_channels(guild_id) List channels in a server

discord_send_message(channel_id, content) Send a message to a Discord channel

Polymarket

get_polymarket_events() Browse active prediction market events

get_polymarket_event(event_id) Detailed view of a specific event and its markets

search_polymarket(query) Search prediction markets by keyword

Trade Journal

get_trade_journal(limit) Historical trade log with P&L

get_trade_stats() Aggregated trading statistics (win rate, PnL, etc.)

TradingView Alerts

get_tv_alerts(limit) Recent TradingView webhook alerts

System & Health

health() API gateway health check

api_info() API version, endpoints, and capabilities

list_tools() List all 80+ available tools

tool_info(tool_name) Detailed info for a specific tool

call_tool(tool_name, **kwargs) Generic tool caller — call any tool by name

Error Handling

from sentinel.exceptions import (
    SentinelError,      # Base exception
    AuthError,          # 401 — bad token/key
    ForbiddenError,     # 403 — insufficient permissions
    RateLimitError,     # 429 — rate limited (auto-retried)
    ToolNotFoundError,  # 404 — unknown tool name
)

try:
    client.get_crypto_price("bitcoin")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except AuthError:
    print("Invalid credentials")