IPOR Fusion Python SDK

ipor_fusion is the official Python SDK for IPOR Fusion Plasma Vaults — typed abstractions for DeFi protocol interactions on EVM chains through a fuse adapter pattern.

Maintained by IPOR Labs AG.

Documentation · SDK docs · llms.txt for AI agents · Hosted MCP server · Example bot · Contracts

Workflow
Social
Code

Quickstart

Install

pip install ipor-fusion

Connect and execute

from ipor_fusion import Web3Context, PlasmaVault, AaveV3SupplyFuse
from web3 import Web3

# 1. Create a Web3 context with your provider and private key
ctx = Web3Context.from_url(
    url="https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY",
    private_key="0x...",
)

# 2. Wrap the PlasmaVault contract
vault = PlasmaVault(ctx, Web3.to_checksum_address("0xVAULT_ADDRESS"))

# 3. Build a fuse action (e.g. supply USDC to Aave V3)
fuse = AaveV3SupplyFuse(Web3.to_checksum_address("0xFUSE_ADDRESS"))
action = fuse.supply(
    asset=Web3.to_checksum_address("0xUSDC_ADDRESS"),
    amount=1_000_000,  # 1 USDC (6 decimals)
)

# 4. Execute on-chain (execute() returns a Call; .send() signs and submits it)
receipt = vault.execute([action]).send()

Fuse, factory and manager addresses per chain are published in ipor-abi (mainnet/mainnet-<chain>-fusion/addresses.json). A fuse must also be registered on the vault; vault.get_fuses().call() lists the registered ones.

Amounts are raw on-chain integers (Amount, Shares in ipor_fusion.types); the SDK never scales by decimals.

Read, send, or simulate

Every wrapper method returns a Call instead of executing. The same Call powers all three modes:

from ipor_fusion import VaultSimulator

total = vault.total_assets().call()          # eth_call -> Amount
receipt = vault.execute([action]).send()     # signed tx -> TxReceipt
payload = vault.execute([action]).calldata   # raw bytes for an external signer

# Simulate first via eth_simulateV1 (no local node); alpha is the account allowed to call execute()
sim = VaultSimulator(ctx.web3, vault=vault.address, alpha=Web3.to_checksum_address("0xALPHA"))
sim.observe("before", vault.total_assets())
sim.execute([action])
sim.observe("after", vault.total_assets())
result = sim.run()
if result.all_success:
    print(result.get("after") - result.get("before"))

CLI Quickstart

The SDK ships with a fusion CLI for inspecting and managing Plasma Vaults from the terminal.

You need an RPC provider URL — get a free key at Alchemy or Infura.

# Install with CLI extras (pipx keeps dependencies isolated)
pipx install 'ipor-fusion[cli]'

# Configure an RPC provider (auto-detects chain ID)
fusion config set-provider https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY

# Inspect a vault (auto-saves to config on first use)
fusion vault info 0xB8a451107A9f87FDe481D4D686247D6e43Ed715e --chain-id ethereum

# List saved vaults
fusion vault list

# Inspect a Morpho Blue market or MetaMorpho vault
fusion market morpho-blue 0xMARKET_ID --chain ethereum
fusion market meta-morpho 0xVAULT_ADDRESS --chain ethereum

MCP Server

Two ways to reach IPOR Fusion from an MCP-compatible AI assistant (Claude Code, Cursor, Windsurf, etc.).

Hosted server (no install)

https://mcp.ipor.io/mcp is public, unauthenticated and read-only — inspect any Fusion vault without your own RPC key.

claude mcp add --transport http ipor-fusion https://mcp.ipor.io/mcp

{
  "mcpServers": {
    "ipor-fusion": {
      "type": "http",
      "url": "https://mcp.ipor.io/mcp"
    }
  }
}

Tools: vaults_list, vault_info, vault_oracle_mapping, fusion_addresses_list, fusion_address_names, fusion_address_lookup, market_morpho_blue, market_meta_morpho.

Local server (from the SDK)

The SDK ships a fusion-mcp server that exposes the CLI over MCP, against your own RPC providers and local config.

# Install with MCP extras (pipx keeps dependencies isolated)
pipx install 'ipor-fusion[mcp]'

Add to your MCP client configuration (e.g. .mcp.json):

{
  "mcpServers": {
    "ipor-fusion": {
      "command": "fusion-mcp",
      "type": "stdio"
    }
  }
}

Available tools:

Configure providers and vaults via fusion config or the MCP config tools first.

Besides the tools, fusion-mcp serves the guide from ipor_fusion.guide as the resources fusion://glossary, fusion://architecture, fusion://invariants and fusion://quickstart (the executed deploy-and-operate walk), and the prompts quickstart, deploy_vault, analyze_vault, trace_oracle_pricing and explain_fuse (slash commands in clients that support MCP prompts).

Agent skills

skills/ipor-deploy-vault/SKILL.md teaches a coding agent the full clone → roles → market → access posture → deposit → execute walk, with the invariants and the revert selectors, before it writes vault code. Its body is fusion://invariants and fusion://quickstart from ipor_fusion.guide verbatim (a test keeps them identical), so the skill and the MCP resources are one text with two delivery paths. It follows the Agent Skills format and versions with the SDK. One install per machine:

# Claude Code — plugin with the skill and the hosted MCP server
/plugin marketplace add IPOR-Labs/ipor-fusion.py
/plugin install ipor-fusion@ipor-fusion

# Codex CLI, Gemini CLI, Cursor — the skill; add the MCP server as shown above
npx skills add IPOR-Labs/ipor-fusion.py -g -a codex      # or gemini-cli, cursor

Common errors

Reverts on the deploy-and-configure path, keyed by selector so a failed transaction is greppable. This table and the full invariants ship in the wheel as ipor_fusion.guide, which fusion-mcp serves as fusion://invariants.

clone() grants the owner only Roles.OWNER_ROLE (1). OWNER grants Roles.ATOMIST_ROLE (100), which administers Roles.FUSE_MANAGER_ROLE (300, configuration), Roles.ALPHA_ROLE (200, execute) and Roles.WHITELIST_ROLE (800, deposit on a private vault).

Configuration order on a fresh vault: add_fuses → grant_market_substrates → add_balance_fuse → execute; all three configuration steps are mandatory.

A flash-loan fuse also needs update_callback_handler(handler, sender, selector) before its first execute: Morpho Blue calls back onMorphoFlashLoan(uint256,bytes), the Euler EVC onEulerFlashLoan(bytes), and an unregistered callback reverts HandlerNotFound().

The full clone → configure → deposit → execute sequence is exercised in tests/test_simulate_vault_from_scratch_base.py.

Custom errors of the crosschain contracts decode by name: importing ipor_fusion.crosschain registers their signatures (CROSSCHAIN_ERROR_SIGNATURES), so a simulated or sent call that reverts reads NavSettledStale(8453) in SimulationResult.revert_reason and TransactionError instead of a bare selector. register_custom_errors([...]) adds your own, and SimulationResult.raise_for_failure() raises SimulationError naming the first failed call.

Vault construction examples

Runnable, canonical examples for building and configuring a vault from scratch live in examples. They preview and simulate through eth_simulateV1 — nothing is ever signed or broadcast.

• Simple Aave V3 supply vault — start here for vault creation, role bootstrap, and configuring a single supported market.
• Advanced Euler V2 credit-market vault — continue here for composing multiple functional fuses, typed Euler substrates and sub-accounts, and an ordered collateral → borrow → repay → unwind lifecycle.
• External-state margin leg — a vault whose capital sits off-chain: typed market-50 substrates, a dual-custodian propose/confirm marking the NAV, the scheduled-withdrawal prep an alpha performs, and a mismatched confirmation being rejected.
• Crosschain CCIP lifecycle — a vault whose capital works on another chain: supply USDC from an Arbitrum hub to a HyperEVM spoke over CCIP, attest the remote balance with two keys, deposit and redeem on the spoke, recall and claim, driven through CrosschainLane and relayed by CrosschainSimulator.

export BASE_PROVIDER_URL="https://base-mainnet.g.alchemy.com/v2/YOUR_KEY"
uv run python examples/simple_aave_v3_supply_base.py
uv run python examples/advanced_euler_v2_credit_market_base.py
uv run python examples/external_state_margin_leg_base.py
uv run python examples/crosschain_ccip_usdc_arbitrum_hyperevm.py  # needs ARBITRUM_PROVIDER_URL and HYPEREVM_PROVIDER_URL

No RPC key? BASE_PROVIDER_URL=https://mainnet.base.org (Base's public RPC) runs the examples out of the box — it supports eth_simulateV1 and serves their pinned blocks. It is rate-limited, so use a dedicated archive node for repeated or CI runs.

Architecture

The SDK uses a fuse adapter pattern:

• Fuses encode protocol-specific calls into FuseAction objects (pure calldata, no state)
• PlasmaVault batches and executes FuseAction sequences on-chain via execute(); a batch is atomic
• Web3Context manages provider connections, signing, and transaction dispatch
• Call is the lazy result of every wrapper method: .call(), .send(), .calldata, or feed it to VaultSimulator

Fuse.method()  -->  FuseAction  -->  PlasmaVault.execute([actions])  -->  Call  -->  .send() / simulate

Core modules (ipor_fusion.core)

Supported protocols (ipor_fusion.fuses)

The mainnet crosschain POC vault uses a keccak-derived market ID, not 54. Use crosschain_market_id("IPOR_FUSION_CROSSCHAIN_USDC_POC_V1") for that deployment; open_lane discovers the vault's actual market grants rather than assuming 54. | HyperCore (Hyperliquid, market 55) | HyperCoreDepositFuse, HyperCoreMarginFuse, HyperCoreSendFuse, HyperCoreOrderFuse, HyperCoreCancelFuse, HyperCoreBuilderFeeFuse, HyperCoreSubstrates |

Readers (ipor_fusion.readers)

Read-only aggregators over positions and health, no fuses involved:

Supported networks

• Ethereum mainnet
• Arbitrum One
• Base

Development

uv sync --all-extras                                       # Install dependencies
uv run pytest tests/test_fuse_encoding.py -n auto -v       # Unit tests (fast, offline)
uv run pytest -v -s                                        # All tests (needs `.*_PROVIDER_URL` variables in `.env`)
uv run ruff format ./                                      # Format
uv run ruff check ./                                       # Lint
uv run pyright                                             # Type check

Integration tests need provider URLs in .env (eth_simulateV1 at a pinned fork block — no local node):

cp .env.example .env
# Edit .env with ARBITRUM_PROVIDER_URL, ETHEREUM_PROVIDER_URL, BASE_PROVIDER_URL

Contributor and coding-agent instructions (commands, conventions, invariants, domain rules) live in AGENTS.md.

Examples

For full usage patterns, see the example repository: ipor-fusion-alpha-example