Metadata-Version: 2.4
Name: modexiaagentpay
Version: 0.6.1
Summary: Modexia AgentPay — Python SDK for agent wallets & payments (USDC)
Author-email: Modaniels <modaniels@modexia.software>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Modaniel/SDKs
Project-URL: Repository, https://github.com/Modaniel/SDKs
Project-URL: Documentation, https://github.com/Modaniel/SDKs/docs
Project-URL: Changelog, https://github.com/Modaniel/SDKs/releases
Keywords: modexia,agentpay,sdk,payments,usdc
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: requests-mock; extra == "dev"
Dynamic: license-file

<div align="center">
  <img src="assets/modexialogo.png" alt="Modexia Logo" width="120" style="border-radius: 20px; margin-bottom: 20px;" />
  <h1>🚀 Modexia Python SDK</h1>
  <p><b>The ultimate Python client for AI Agents to seamlessly interact with Modexia's AgentPay API.</b></p>
  
  [![PyPI version](https://badge.fury.io/py/modexiaagentpay.svg)](https://badge.fury.io/py/modexiaagentpay)
  [![Python versions](https://img.shields.io/pypi/pyversions/modexiaagentpay.svg)](https://pypi.org/project/modexiaagentpay/)
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
</div>

<br />

Welcome to the **Modexia Python SDK** (`modexiaagentpay`). Built from the ground up to give your AI agents and Python applications frictionless access to Modexia's wallet and payment infrastructure. Enable your AI to hold, manage, and transfer value with just a few lines of code!

---

## 🌟 Getting Started: Your API Key

Before writing your first integration, you will need a Modexia developer account and an API key. 

1. **Visit [modexia.software](https://modexia.software)**
2. Create or log into your developer account.
3. Navigate to your dashboard and generate your **API Key**.

For deep dives, architecture, and advanced agentic payment flows, dive into our **[Full Documentation](https://modexia.software/docs)**.

---

## 🏗 System Architecture & Flow

Currently, the SDK uses an **API Key-based Custodial Model** for maximum developer velocity.

```mermaid
sequenceDiagram
    participant Agent as 🤖 AI Agent (Your App)
    participant SDK as 📦 Modexia Python SDK
    participant API as 🌐 Modexia AgentPay API
    participant Chain as ⛓️ Settlement Layer

    Agent->>SDK: transfer(recipient, amount, wait=True)
    SDK->>API: POST /v1/payments (with API Key)
    API-->>SDK: Transaction Pending (TxHash)
    
    rect rgb(40, 44, 52)
    Note over SDK, API: SDK Automatically Polls API
    loop Polling Status
        SDK->>API: GET /v1/payments/{id}/status
        API-->>SDK: Status: Pending...
    end
    end
    
    API->>Chain: Finalizes Settlement On-Chain
    Chain-->>API: Transaction Confirmed
    API-->>SDK: Status: Completed
    SDK-->>Agent: Returns Full Receipt! 🎉
```

> **Note on Future Evolution:** We are actively developing a transition to **Fully Trustless State Channels (EIP-712)**. In future versions, agents will manage their own private keys and sign off-chain cryptographic receipts natively, removing Modexia as a trusted middleman. See our [Architecture Docs](../docs/architecture.md) for details.

---

## ✨ Top-Level Features

- **Built for AI Agents:** Designed specifically for programmatic access to agent wallets and payments without complex cryptography. Includes Agent Memory via transaction history.
- **Intent-Based Idempotency:** Automatically deduplicates identical payment requests from your agents using intent hashing.
- **Async & "Swarm" Support:** High-concurrency operations powered by blazing fast implementations in both synchronous and `asyncio` models.
- **Fully Typed:** Returns robust Python dataclasses for exceptional developer experience and editor autocompletion.
- **Reliable Networking:** Built-in retry and exponential backoff mechanisms to gracefully handle transient network errors.

---

## 📦 Installation

Install the production-ready package directly from PyPI:

```bash
pip install modexiaagentpay
```

*For local development and contribution:*
```bash
git clone https://github.com/Modaniel/SDKs.git
cd SDKs
pip install -e packages/SDKs/pythonSdk
```

---

## 🚀 Quick Start Guide

Initialize the client with your Modexia API key and empower your application to make real-world transactions instantly.

```python
from modexia import ModexiaClient

# 1. Initialize the client using the API key you generated at modexia.software
# (It also respects the MODEXIA_BASE_URL environment variable!)
client = ModexiaClient(api_key="mx_test_your_api_key_here")

# 2. Check your agent's wallet balance & history
try:
    balance = client.retrieve_balance() # Or client.get_balance()
    history = client.get_history(limit=5)
    print(f"💰 Current wallet balance: {balance} credits")
except Exception as e:
    print(f"Failed to fetch balance: {e}")

# 3. Execute a secure transfer!
# Setting wait=True ensures the SDK polls until the blockchain confirms the transaction.
receipt = client.transfer(
    recipient="0xabc123456789def0123456789abc0123456789def", 
    amount=5.0, 
    wait=True
)

# Strongly-typed dataclasses mean your editor knows `receipt.txId` exists!
if receipt.success:
    print(f"✅ Transfer successful! TX ID: {receipt.txId}")
```

### Async Usage (Swarm Mode)

For high-concurrency loops or AutoGPT-style agent networks:

```python
import asyncio
from modexia import AsyncModexiaClient

async def main():
    client = AsyncModexiaClient(api_key="mx_test_your_api_key_here")
    receipt = await client.transfer("0xabc...", 5.0)
    print(f"Status: {receipt.status}")
    await client.aclose()

asyncio.run(main())
```

---

## 🛠 API Reference

### `ModexiaClient` & `AsyncModexiaClient`
The core classes for all network operations.

```python
ModexiaClient(
    api_key: str, 
    timeout: int = 15, 
    base_url: Optional[str] = None, 
    validate: bool = True
)
```

#### Core Methods
| Method | Description | Returns |
|--------|-------------|---------|
| `retrieve_balance()` / `get_balance()` | Fetches the current available balance of your agent's wallet. | `str` |
| `transfer(recipient, amount, idempotency_key=None, wait=True)` | Send funds to a destination. Uses intent-hashing to prevent duplicate charges. Raises `TimeoutError` if `wait=True` exceeds 30s. | `PaymentReceipt` |
| `get_history(limit=5)` | Fetch the recent transaction history for Agent memory. | `TransactionHistoryResponse` |
| `open_channel(...)`, `consume_channel(...)`, `settle_channel(...)` | Utilize High-Frequency Vaults to process thousands of zero-fee micropayments per second off-chain. | Varied |
| `smart_fetch(url, ...)` | Auto-negotiates 402 HTTP paywalls automatically. Explicitly raises network/auth errors but catches payment errors. | `Response` |

### 🛑 Exception Handling

The SDK provides robust error mapping to help your agent gracefully recover from failures. You can import these directly from the `modexia` package:

```python
from modexia import ModexiaClient, ModexiaAuthError, ModexiaPaymentError, ModexiaNetworkError
```

```mermaid
graph TD;
    Exception-->TimeoutError["TimeoutError: wait=True Polling exceeded 30s"];
    Exception-->ModexiaError;
    ModexiaError-->ModexiaAuthError["ModexiaAuthError: Key/Auth Issues"];
    ModexiaError-->ModexiaPaymentError["ModexiaPaymentError: Insufficient Funds / API Responses with success=False"];
    ModexiaError-->ModexiaNetworkError["ModexiaNetworkError: Connection Drops / Invalid JSON payloads"];
```

---

## 🤝 Contributing to Open Source

We actively welcome community contributions to make this SDK even better. 

1. **Fork & Branch:** Open a Pull Request targeting the `develop` branch.
2. **Backward Compatibility:** Please keep API contracts stable. `ModexiaClient`, `transfer()`, and `retrieve_balance()` are canonical.
3. **Testing:** Make sure tests pass locally before submitting.

```bash
# Run tests from the repository root
pytest -q packages/SDKs/pythonSdk
```

---

## 📄 License & Support

**modexiaagentpay** is totally open-source and governed by the [MIT License](LICENSE).

Need help scaling your agent swarm? Hit rate limits? Reach out to our engineering team or explore the docs at [modexia.software](https://modexia.software).
