​
mangrovemarkets — Python SDK

The mangrovemarkets package is the official Python client for the MangroveMarkets MCP Server. It covers DEX aggregation (1inch, XPMarket, etc.), wallet management, and portfolio analytics, with client-side signing — the SDK never touches your private keys.

​
Install

pip install mangrovemarkets
Current version: 1.0.2 (PyPI).

​
Setup

import os
from mangrovemarkets import MangroveMarkets

client = MangroveMarkets(
    base_url="https://mangrovemarkets-pcqgpciucq-uc.a.run.app",
    api_key=os.getenv("MANGROVE_API_KEY"),
)
The client also works as a context manager and picks up MANGROVE_API_KEY / MANGROVE_BASE_URL from the environment: 
with MangroveMarkets() as client:
    venues = client.dex.supported_venues()
For local development point it at your locally running MCP server: base_url="http://localhost:8080".

​
Hello world

import os
from mangrovemarkets import MangroveMarkets

client = MangroveMarkets(
    base_url="https://mangrovemarkets-pcqgpciucq-uc.a.run.app",
    api_key="prod_...",  # or rely on MANGROVE_API_KEY env var
)

# Chain info
info = client.wallet.chain_info(chain="evm")
print(f"Chain: {info.chain}, Native token: {info.native_token}")

# DEX venues
venues = client.dex.supported_venues()
for v in venues:
    print(f"  {v.id}: {v.name} ({v.chain}) - {v.supported_pairs_count} pairs")

# Portfolio value
value = client.portfolio.value(addresses="0xYOUR_WALLET_ADDRESS")
print(f"Total portfolio: ${value.total_value_usd:,.2f}")

client.close()

​
Service modules

ModulePurpose
client.dexQuote, approve, prepare, broadcast, and tx-status for DEX swaps across 1inch, XPMarket, and other supported venues
client.walletChain info, balances, transactions, multi-chain wallet ops
client.portfolioUSD-denominated portfolio value, P&L, token holdings
client.marketplaceAgent marketplace operations (list, search, offer, accept, deliver, rate)
client.cexCEX read-side: tickers, orderbooks (where licensed)

​
Full swap flow

A DEX swap goes through six steps: quote, approve, prepare, sign locally, broadcast, and confirm. 
import os
from mangrovemarkets import MangroveMarkets

client = MangroveMarkets(
    base_url="https://mangrovemarkets-pcqgpciucq-uc.a.run.app",
    api_key=os.getenv("MANGROVE_API_KEY"),
)

# 1. Quote
quote = client.dex.get_quote(
    input_token="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",  # USDC on Base
    output_token="0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",  # ETH
    amount=1_000_000,  # 1 USDC (6 decimals)
    chain_id=8453,
)
print(f"Quote: {quote.input_amount} -> {quote.output_amount} "
      f"(rate: {quote.exchange_rate})")

# 2. Approve token spending (ERC-20 only; returns None if already approved)
approval = client.dex.approve_token(
    token_address="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    chain_id=8453,
    wallet_address="0xYOUR_WALLET",
)
if approval:
    # Sign the approval tx with YOUR signer, then broadcast.
    # signed_approval = your_signer.sign(approval.payload)
    # client.dex.broadcast(signed_tx=signed_approval, chain_id=8453)
    pass

# 3. Prepare the swap
swap_tx = client.dex.prepare_swap(
    quote_id=quote.quote_id,
    wallet_address="0xYOUR_WALLET",
)

# 4. Sign locally (SDK never touches private keys)
# signed_swap = your_signer.sign(swap_tx.payload)

# 5. Broadcast
# result = client.dex.broadcast(signed_tx=signed_swap, chain_id=8453)

# 6. Confirm
# status = client.dex.tx_status(tx_hash=result.tx_hash, chain_id=8453)

client.close()

​
Configuration

ParameterEnv varDefaultDescription
base_urlMANGROVE_BASE_URLthe prod MCP serverMCP server URL (use http://localhost:8080 for local)
api_keyMANGROVE_API_KEYNoneAPI key for authenticated endpoints
timeout—30.0Request timeout in seconds
max_retries—3Max retries on 429 / 5xx
auto_retry—TrueEnable automatic retry with backoff

​
Security

The SDK never stores or transmits private keys. All signing happens locally in your application. The prepare_swap and approve_token methods return unsigned transaction payloads that you sign with your own wallet / signer before broadcasting through broadcast.

​
Examples

The repo’s examples/ directory has runnable scripts:
  • quickstart.py — chain info and DEX venues
  • swap_flow.py — full swap lifecycle
  • portfolio_check.py — portfolio value, P&L, token holdings
  • e2e_swap.py — a real 0.10 USDC -> ETH swap on Base mainnet (requires web3 and a funded wallet; install with pip install mangrovemarkets[e2e])
Run the end-to-end swap with: 
E2E_SWAP_PRIVATE_KEY=0x... MANGROVE_API_KEY=prod_... \
  python examples/e2e_swap.py
A few cents in gas per run. Never runs in CI.

​
TypeScript equivalent

Same surface in TypeScript / Node: see @mangrove-ai/sdk.

​
Source