# Modexia AgentPay SDK Documentation

## Overview
Modexia is a financial infrastructure layer for autonomous AI agents. It bridges Web2 authentication (Supabase) with Web3 Smart Contract Accounts (ERC-4337 on Base Network).

## Installation
```
pip install modexiaagentpay
```

## Initialization
Authentication and environment selection are handled via the API Key prefix.
- `mx_test_...` -> Targets Sandbox (Base-Sepolia)
- `mx_live_...` -> Targets Production (Base-Mainnet)

```python
from modexia import create_client

# Initialize client
# API Key is obtained from https://modexia.software/dashboard
client = create_client(api_key="mx_test_...")
```

## Core Methods

### 1. Transfer Funds (Direct Payment)

Sends USDC to a specific wallet address. The platform charges a 1% fee on top of the amount.

```python
receipt = client.transfer(
    recipient="0x7d5e6fe453ae469fe3b060d7adb1d3d5dfc091df",
    amount=5.00,       # Amount in USDC (Decimal)
    wait=True,         # Poll for blockchain finality (Recommended)
    idempotency_key="task_123" # Optional: Prevent double-spend
)

if receipt['success']:
    print(f"TxHash: {receipt['txHash']}")
```

### 2. Smart Fetch (x402 / Paywall Negotiation)

A wrapper around HTTP GET. Automatically detects 402 Payment Required, parses the WWW-Authenticate header for price/destination, pays the invoice via Modexia, and retries the request with a proof-of-payment header.

```python
# Automatically pays if status is 402
response = client.smart_fetch("https://premium-api.com/data")

print(response.json())
```

### 3. Check Balance

Returns the available USDC balance of the Agent's Smart Contract Wallet.

```python
balance = client.retrieve_balance()
print(f"Balance: {balance} USDC")
```

## Error Handling

The SDK raises specific exceptions for control flow:

- `ModexiaAuthError`: Invalid API Key.
- `ModexiaPaymentError`: Insufficient funds, daily limit exceeded (server-side policy), or blockchain revert.
- `ModexiaNetworkError`: API Gateway unreachable.

## Architecture Notes

- **Gas**: Gas fees are sponsored by the Modexia Paymaster (SCA). Agents do not need native tokens.
- **Policies**: Spending limits (Daily/Hourly) are enforced server-side. Payments exceeding limits will fail immediately without hitting the blockchain.