​
mangroveai — Python SDK

The mangroveai package is the official Python client for the MangroveAI platform. It wraps every public REST endpoint with typed methods and handles auth, retries, and pagination.

​
Install

pip install mangroveai
Requires Python 3.10+. Current version: 1.0.2 (check PyPI for latest).

​
Setup

  1. Create an account at the Developer Portal.
  2. Go to Settings → API Keys and generate a key.
  3. Set it as an environment variable:
export MANGROVE_API_KEY=prod_your_key_here

​
Hello world

from mangrove_ai import MangroveAI

client = MangroveAI()  # reads MANGROVE_API_KEY from env

# Discover signals (category is optional: momentum, trend, volume, volatility, patterns, onchain)
signals = client.signals.list(category="momentum", limit=10)
for s in signals.items:
    print(s.name, s.signal_type, s.metadata.description)

​
Service modules

The client exposes these service attributes, each mapping to a domain in the REST API.
ModulePurpose
client.signalsList, validate, and evaluate trading signals
client.strategiesCRUD for strategies; manage entry/exit rules
client.backtestingRun historical backtests, retrieve results
client.executionReal-time strategy evaluation, position state
client.ai_copilotConversational strategy creation
client.crypto_assetsAsset metadata, OHLCV, market data
client.on_chainSmart-money flows, DEX/perp trades, whale activity (Nansen + WhaleAlert) — see On-Chain API
client.defiTVL/chain/stablecoins (any plan) + Pro: token unlocks, perp funding, treasuries, ETF flows, lending rates (Pro/Startup/Enterprise, 1k/mo cap) — see DeFi API
client.socialTopic sentiment, mentions, user influence (X / Twitter) — see Social API
client.docsSearch the knowledge base from your code
client.kbSignal and indicator metadata via the KB server

​
Common patterns

​
Create a strategy and run a backtest

strategy = client.strategies.create(
    name="RSI mean reversion",
    entry_rules={
        "trigger": {"name": "rsi_oversold", "params": {"window": 14, "threshold": 30}},
        "filter":  {"name": "is_above_sma",  "params": {"window": 200}},
    },
    exit_rules={"take_profit_pct": 5, "stop_loss_pct": 2},
)

result = client.backtesting.run(
    strategy_id=strategy.id,
    symbol="BTC-USD",
    timeframe="1h",
    start="2025-01-01",
    end="2026-01-01",
)
print(result.metrics.sharpe_ratio, result.metrics.max_drawdown)

​
Evaluate a signal on the platform

df = ...  # your OHLCV data as a pandas DataFrame
fired = client.signals.evaluate(
    name="macd_bullish_cross",
    params={"window_fast": 12, "window_slow": 26, "window_sign": 9},
    ohlcv=df,
)
For local-only evaluation without an API call, use mangrove-kb instead.

​
Use the AI copilot

The Copilot is a stateful chat agent backed by OpenAI. Start a conversation, send messages until the agent has enough context, then save the generated strategy as a MangroveAI draft. 
# 1. Start a session.
conv = client.ai_copilot.start_new_conversation()

# 2. Chat. `chat()` blocks until the assistant responds (default
#    180s timeout — Copilot state-machine turns can run 60-180s).
reply = client.ai_copilot.chat(
    conv.session_id,
    "I want a momentum strategy for ETH on the 1h timeframe.",
)
print(reply.content)

# 3. Refine.
reply = client.ai_copilot.chat(
    conv.session_id,
    "MACD bullish cross for entry, MACD bearish cross for exit.",
    timeout=240.0,  # bump for backtest-heavy turns
)

# 4. Pull the rendered strategy_config and save it as a draft.
ctx = client.ai_copilot.get_conversation(conv.session_id)
if ctx.strategy_config:
    saved = client.ai_copilot.save_strategy(
        ctx.strategy_config, name="ETH 1h momentum"
    )
    print("strategy_id:", saved.result["strategy_id"])
For callers that want to drive their own polling instead of blocking, use client.ai_copilot.chat_async(session_id, message) — it returns the raw 202 submission and you poll get_conversation(session_id) until processing_status flips to "complete". See a runnable end-to-end demo at examples/ai_copilot_quickstart.py.

​
Query on-chain smart-money activity

client.on_chain covers Mangrove’s full Nansen Pro plan + WhaleAlert Enterprise. Filters and sort orders pass straight through to the upstream provider, so you can use the same vocabulary the Nansen API itself accepts. 
# Smart-money DEX trades by Fund-labelled wallets, most recent first
trades = client.on_chain.get_smart_money_dex_trades(
    chains=["ethereum"],
    filters={"include_smart_money_labels": ["Fund"]},
    order_by=[{"field": "block_timestamp", "direction": "DESC"}],
    per_page=10,
)
for t in trades.trades or []:
    print(t["block_timestamp"], t["trader_address_label"], t["action"], t["value_usd"])

# Token-scoped: every DEX trade on UNI in the last week
uni_trades = client.on_chain.get_token_dex_trades(
    "uniswap", chain="ethereum",
    date_from="2026-05-22", date_to="2026-05-28",
    per_page=20,
)
print(f"{uni_trades.count} trades on contract {uni_trades.contract_address}")

# Per-wallet-category flows for UNI (not available for stablecoins)
flows = client.on_chain.get_token_flows(
    "uniswap", chain="ethereum",
    date_from="2026-05-22", date_to="2026-05-28",
)
for f in flows.flows or []:
    print(f["date"], "price:", f["price_usd"], "holders:", f["holders_count"])
See the full surface on the On-Chain API reference and a runnable customer example at examples/on_chain_nansen.py.

​
Auth options

  • API key (recommended for backend code): client = MangroveAI(api_key="prod_...") or via env.
  • JWT (for short-lived tokens): client = MangroveAI(jwt="...").
See Authentication for the full flow.

​
Source