Iwa

PyPI version Docker Pulls Python 3.12+ Tests Coverage License: MIT

Iwa (岩), meaning "rock" in Japanese, symbolizes the unshakeable stability and immutable foundation required for secure financial infrastructure.



Iwa is a Python framework designed for managing crypto wallets and interacting with smart contracts and crypto protocols in a secure, modular, and extensible way. It's ideal for building autonomous agents and applications that require blockchain interactions.

Features

  • Secure Key Storage: Private keys are encrypted with AES-256-GCM and stored safely. They are never exposed to the application layer; signing happens internally via the KeyStorage class.

  • Modularity (Plugins): Protocols and features are implemented as plugins, loaded dynamically. Currently supports Gnosis (Safe, CowSwap) and Olas (Registry, Services, Staking).

  • Multi-Chain Support: Native support for Gnosis Chain, Ethereum, and Base, with easy extensibility for others.

  • Robust Transaction Management:

    • RPC Rotation: Automatically switches RPC providers if one fails or is rate-limited.
    • Rate Limiting: Token bucket algorithm with automatic backoff.
    • Retry Logic: Automatic retries with exponential backoff for transient failures.

  • MCP Server: Expose all wallet and Olas operations as Model Context Protocol tools, enabling AI agents (Claude, Cursor, etc.) to interact with the blockchain directly.

  • CLI & TUI Integration: Interact with your wallet via a unified CLI or a beautiful Terminal User Interface built with Textual.

  • Web API: RESTful API built with FastAPI for web-based integrations.

  • Modern Tooling: Managed with uv, Justfile for automation, and ready for Docker deployment.

Architecture

iwa/
├── core/               # Core wallet functionality
│   ├── keys.py         # KeyStorage - Encrypted key management
│   ├── wallet.py       # Wallet - High-level interface
│   ├── chain/          # Blockchain interface with rate limiting
│   ├── services/       # Service layer (accounts, balances, transactions)
│   └── contracts/      # Contract abstractions (ERC20, Safe)
├── mcp/                # MCP server (Model Context Protocol)
│   └── tools.py        # 23 core wallet tools
├── plugins/            # Protocol integrations
│   ├── gnosis/         # Safe multisig and CowSwap DEX
│   └── olas/           # Olas Registry, Services, Staking + 17 MCP tools
├── tui/                # Terminal User Interface (Textual)
└── web/                # Web API (FastAPI)

Key Components

Component Description
KeyStorage Encrypts/decrypts private keys, provides internal signing
Wallet Main high-level interface for user interactions
ChainInterface Manages Web3 connections with rate limiting and RPC rotation
TransactionService Handles transaction signing and sending with retry logic
PluginService Dynamically loads and manages protocol plugins

Setup & Usage

Prerequisites

  • Python 3.12+
  • uv package manager

Installation

# Install from PyPI
pip install iwa

# Or using uv (recommended for tools)
uv tool install iwa

# Or from source
git clone https://github.com/dvilelaf/iwa.git
cd iwa
just install

Configuration

Create a secrets.env file with your configuration:

WALLET_PASSWORD=your_secure_password
GNOSIS_RPC=https://rpc.gnosis.io,https://gnosis.drpc.org
ETHEREUM_RPC=https://mainnet.infura.io/v3/YOUR_KEY
BASE_RPC=https://mainnet.base.org

# Testing mode (default: true uses Tenderly test RPCs)
TESTING=false

# Optional
COINGECKO_API_KEY=your_api_key

Running

# Launch TUI
just tui

# Launch Web UI
just web

# Use CLI
iwa wallet list --chain gnosis

# Start MCP server (for AI agent integration)
iwa mcp --transport sse --port 18080

MCP Agent Integration

The MCP server exposes 40 tools covering wallet operations, Olas service management, and staking. Example agent scripts for Claude, OpenAI GPT, and Gemini are in scripts/mcp/:

# Start the MCP server
iwa mcp --transport sse --port 18080

# Claude (pip install anthropic)
export ANTHROPIC_API_KEY=sk-ant-...
python scripts/mcp/claude_agent.py

# OpenAI GPT (pip install openai)
export OPENAI_API_KEY=sk-...
python scripts/mcp/openai_agent.py

# Gemini (pip install google-generativeai)
export GOOGLE_API_KEY=AIza...
python scripts/mcp/gemini_agent.py

See MCP documentation for the full tool reference and Claude Desktop configuration.

Running Tests

just test

Security Checks

just security      # Runs gitleaks, bandit, and pip-audit
just wallet-check  # Verifies password, keys, and mnemonic integrity

Docker

# Pull from Docker Hub
docker pull dvilelaf/iwa:latest

# Build locally
just docker-build
just docker-run

Plugins

Plugins are located in src/iwa/plugins. Currently supported:

Gnosis Plugin

  • Safe: Create and manage Safe multisig wallets
  • CowSwap: Token swaps via CoW Protocol with MEV protection, Max balance support, and auto-refreshing UI

Olas Plugin

  • Registry: Interact with Olas service registry
  • Services: Create, deploy, and manage Olas services
  • Staking: Stake/unstake services and claim rewards

Transaction Flow

  1. Preparation: A high-level method prepares a raw transaction dictionary
  2. Delegation: The transaction is passed to TransactionService
  3. Signing: KeyStorage decrypts the key in memory, signs, and wipes the key
  4. Sending: The signed transaction is sent via ChainInterface
  5. Recovery: Automatic RPC rotation and gas bumping on failures
  6. Receipt: Transaction receipt is returned upon success

Documentation

Full documentation is available in the docs/ directory:

# Serve docs locally
just docs-serve

# Build static docs
just docs-build

Development

# Format code
just format

# Lint code
just check

# Type check
just types

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for dvilelaf from gravatar.com dvilelaf

Requires

Python <4.0, >=3.12

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

iwa-0.8.9.tar.gz (656.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

iwa-0.8.9-py3-none-any.whl (787.0 kB view details)

Uploaded Python 3

File details

Details for the file iwa-0.8.9.tar.gz.

File metadata

  • Download URL: iwa-0.8.9.tar.gz
  • Upload date:
  • Size: 656.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for iwa-0.8.9.tar.gz
Algorithm Hash digest
SHA256 dd6f1a0c647849b287daa287e5d8a4e01a6741b58ee804ec06d393b5734775f9
MD5 fb61f6971aa186fd1591d57d8b7a9b78
BLAKE2b-256 2f33c88999d71d2dbce82bbcd470bdb156ca782a675b0d28ee2c41043a6c983a

See more details on using hashes here.

File details

Details for the file iwa-0.8.9-py3-none-any.whl.

File metadata

  • Download URL: iwa-0.8.9-py3-none-any.whl
  • Upload date:
  • Size: 787.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for iwa-0.8.9-py3-none-any.whl
Algorithm Hash digest
SHA256 93f52e3ffbd7bd1f03c91148c9543942356eddee08d3e8c0102aed0c94c518de
MD5 6b27b8181bfb6413cf31aba0bbb7cfa4
BLAKE2b-256 2767a8823b447b6f2339b7415c992dcfc4e40dd98025311ea258e6441c234235

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

0.8.9 This release

2 files

0.8.8

2 files

0.8.7

2 files

0.8.6

2 files

0.8.5

2 files

0.8.4

2 files

0.8.3

2 files

0.8.2

2 files

0.8.1

2 files

0.8.0

2 files

0.7.9

2 files

0.7.8

2 files

0.7.7

2 files

0.7.6

2 files

0.7.5

2 files

0.7.4

2 files

0.7.1

2 files

0.7.0

2 files

0.6.10

2 files

0.6.9

2 files

0.6.8

2 files

0.6.7

2 files

0.6.6

2 files

0.6.5

2 files

0.6.4

2 files

0.6.3

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.5

2 files

0.5.4

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.5

2 files

0.4.4

2 files

0.4.1

2 files

0.4.0

2 files

0.3.9

2 files

0.3.8

2 files

0.3.7

2 files

0.3.6

2 files

0.3.5

2 files

0.3.4

2 files

0.3.3

2 files

0.2.9

2 files

0.2.8

2 files

0.2.7

2 files

0.2.6

2 files

0.2.5

2 files

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.1.9

2 files

0.1.7

2 files

0.1.6

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

0.0.66

2 files

0.0.65

2 files

0.0.64

2 files

0.0.62

2 files

0.0.61

2 files

0.0.60

2 files

0.0.59

2 files

0.0.58

2 files

0.0.33

2 files

0.0.32

2 files

0.0.31

2 files

0.0.30

2 files

0.0.29

2 files

0.0.28

2 files

0.0.27

2 files

0.0.26

2 files

0.0.25

2 files

0.0.24

2 files

0.0.23

2 files

0.0.21

2 files

0.0.20

2 files

0.0.19

2 files

0.0.18

2 files

0.0.17

2 files

0.0.16

2 files

0.0.15

2 files

0.0.14

2 files

0.0.13

2 files

0.0.12

2 files

0.0.11

2 files

0.0.10

2 files

0.0.2

2 files

Pre-release

0.0.1a6

2 files

Pre-release

0.0.1a5

2 files

Pre-release

0.0.1a4

2 files

Pre-release

0.0.1a3

2 files

Pre-release

0.0.1a2

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page