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:
Newer release available (0.8.9)

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.8.tar.gz (656.2 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.8-py3-none-any.whl (786.8 kB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for iwa-0.8.8.tar.gz
Algorithm Hash digest
SHA256 0e8b62a43adac7e512b80b67f22a443d41ad91fd1c85d79603f62bc52fb093f3
MD5 92232a0ae46e4c389eb7980104af8961
BLAKE2b-256 1d4d500e015d2dfd11df6b234a33508a5664fd57c06c3f0f7a87d723ca909ae6

See more details on using hashes here.

File details

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

File metadata

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

File hashes

Hashes for iwa-0.8.8-py3-none-any.whl
Algorithm Hash digest
SHA256 ae2bfd110edb452081a8f7d2a7e31189909ff8c1e3656db85a176c2acc8a4a25
MD5 c4afb5c6cd56393e84fdc336ce4eefb7
BLAKE2b-256 d4eb89a664e055ddc8c69ecddc5752321e52a7a36d3f0df75377fbea52a84cc9

See more details on using hashes here.

Release history Release notifications | RSS feed

0.8.9

2 files

This release

0.8.8 This release

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