mangrovemarkets 1.0.2

Python SDK for MangroveMarkets — DEX aggregation, wallet management, and portfolio analytics for agents

mangrove-markets

Python SDK for MangroveMarkets -- DEX aggregation, wallet management, and portfolio analytics for agents.

Installation

pip install mangrove-markets

Migrating from mangrovemarkets (the pre-1.0 package name)? Two changes:

- pip install mangrovemarkets
+ pip install mangrove-markets

- from mangrovemarkets import MangroveMarkets
+ from mangrove_markets import MangroveMarkets

The MangroveMarkets client class, every method, every model — unchanged. The old mangrovemarkets PyPI package gets a final 0.1.3 release with a DeprecationWarning and then stops updating. See CHANGELOG.md [1.0.0].

Quickstart

The MangroveMarkets MCP server requires an API key for authenticated endpoints. You can pass it explicitly via the api_key parameter or set the MANGROVE_API_KEY environment variable (the SDK reads it automatically as a fallback).

import os
from mangrove_markets 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()

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 the client at a locally running MCP server:

client = MangroveMarkets(base_url="http://localhost:8080", api_key=os.getenv("MANGROVE_API_KEY"))

Getting an API key

1. Sign up at https://mangrovedeveloper.ai.

2. Go to Settings -> API Keys -> Create.

3. Copy the key -- it is shown only once.

4. Export it as MANGROVE_API_KEY or pass it directly to MangroveMarkets(api_key=...):

   export MANGROVE_API_KEY="prod_..."
   

If you call the API without a valid key, the server returns HTTP 401 with this payload:

{"detail": "Missing or malformed Authorization header. Expected: Bearer <api_key>"}

Full swap flow

A DEX swap goes through six steps: quote, approve, prepare, sign locally, broadcast, and confirm.

import os
from mangrove_markets import MangroveMarkets

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

# 1. Get a 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} (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 local 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 transaction
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

Parameter	Env var	Default	Description
base_url	MANGROVE_BASE_URL	https://mangrovemarkets-pcqgpciucq-uc.a.run.app	MCP server URL (use http://localhost:8080 for local dev)
api_key	MANGROVE_API_KEY	None	API key for authenticated endpoints
timeout	--	30.0	Request timeout in seconds
max_retries	--	3	Max retries on 429/5xx
auto_retry	--	True	Enable automatic retry with backoff

Examples

See the examples/ directory for runnable scripts:

• quickstart.py -- chain info and DEX venues
• swap_flow.py -- full swap lifecycle
• portfolio_check.py -- portfolio value, P&L, and token holdings
• e2e_swap.py -- a real 0.1 USDC → ETH swap on Base mainnet (requires web3 and a funded wallet; install with pip install mangrove-markets[e2e] or pip install web3)

Run the end-to-end swap with:

E2E_SWAP_PRIVATE_KEY=0x... MANGROVE_API_KEY=prod_... python examples/e2e_swap.py

Costs a few cents in gas per run. Never runs in CI.

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.

API reference

This SDK wraps the MangroveMarkets MCP Server REST API. For full tool documentation, parameter details, and response schemas, see the MangroveMarkets-MCP-Server repository.

License

MIT