Metadata-Version: 2.4
Name: ai-economy-sdk
Version: 0.2.1
Summary: Payment-gated MCP server SDK for Algorand
Author-email: risheendra mn <team@aieconomy.com>
License: MIT
Project-URL: Homepage, https://github.com/aieconomy/ai-economy-sdk
Project-URL: Bug Tracker, https://github.com/aieconomy/ai-economy-sdk/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=0.1.0
Requires-Dist: x402-algorand>=0.1.2
Requires-Dist: fastapi>=0.95.0
Requires-Dist: py-algorand-sdk>=2.0.0
Requires-Dist: uvicorn>=0.20.0

# AI Economy SDK

AI Economy SDK is an extension for the Model Context Protocol (MCP) that instantly turns your free AI tools into **paid, on-chain resources**. It wraps any standard MCP tool with the `x402` payment middleware, requiring users to pay per-request via Algorand transactions before the tool executes.

## Features

- **Seamless MCP Integration**: Just decorate your Python functions and build your app.
- **Dynamic Pricing**: Use custom callbacks to charge different amounts based on user inputs or location.
- **Subscription Support (Method B)**: Query the blockchain to bypass payments if the user holds a valid Subscription ASA.
- **Bulk Discounts**: Query indexers to apply automatic half-price or free tiers to power users based on their trailing 30-day usage.
- **Replay Protection**: Automatically drops double-spend attempts based on hash verification.

## Installation

```bash
pip install "ai-economy-sdk>=0.2.1"
```

## Quickstart

```python
import uvicorn
from algosdk import account, mnemonic
from algosdk.v2client import algod
from ai_economy_sdk import AIEconomySDK, DefaultAvmSigner

# 1. Setup Algorand Signer for your Facilitator Wallet
server_pk = mnemonic.to_private_key("YOUR_MNEMONIC_HERE")
server_addr = account.address_from_private_key(server_pk)

# For testing, you must pass an algod_client to the signer!
algod_client = algod.AlgodClient("a"*64, "http://localhost:4001")
signer = DefaultAvmSigner(server_pk, algod_client=algod_client)

# 2. Initialize the SDK
sdk = AIEconomySDK(
    server_signer=signer,
    network="algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=", # CAIP-2 Network
    asset_id="0", # Use "0" for ALGO or your custom ASA ID for USDC
    pay_to_address=server_addr,
    indexer_url="http://localhost:8980" # Required for subscription/bulk features
)

# 3. Define your Dynamic Pricing Callback
def my_pricing(arguments: dict, sender_address: str = None) -> int:
    return 15_000 if arguments.get("premium") else 5_000

# 4. Decorate your Tool
@sdk.add_tool(name="do_work", description="Executes AI task", pricing_func=my_pricing)
async def do_work(premium: bool = False) -> str:
    return "Done! Enjoy your premium service!" if premium else "Done with standard service!"

# 5. Build and Serve
app = sdk.build_app()

if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=8001)
```

## Client Configuration (LocalNet Testing)

To test your SDK server locally, you can use the standard `x402Client` from the `x402-algorand` package. Note that you must pass your `algod_token` to `register_exact_avm_client` to test on LocalNet:

```python
import asyncio
import httpx
from algosdk.v2client import algod
from algosdk.kmd import KMDClient
from x402 import x402Client
from x402.http.clients.httpx import wrapHttpxWithPayment
from x402.mechanisms.avm.exact.register import register_exact_avm_client
from ai_economy_sdk import DefaultAvmSigner

# Note: LocalNet requires 64 'a's for the token!
algod_client = algod.AlgodClient("a"*64, "http://localhost:4001")
sp = algod_client.suggested_params()
CAIP2_NETWORK = f"algorand:{sp.gh}"

def get_funded_localnet_account():
    # Fetch a funded account from the local KMD wallet
    kmd = KMDClient("a"*64, "http://localhost:4002")
    wallets = kmd.list_wallets()
    walletID = wallets[0]['id']
    handle = kmd.init_wallet_handle(walletID, "")
    addresses = kmd.list_keys(handle)
    pk = kmd.export_key(handle, "", addresses[0])
    return pk, addresses[0]

client_pk, client_addr = get_funded_localnet_account()

async def main():
    client_signer = DefaultAvmSigner(client_pk, algod_client=algod_client)
    x402_client = x402Client()

    
    # Configure the client for LocalNet!
    register_exact_avm_client(
        x402_client, client_signer,
        networks=CAIP2_NETWORK, 
        algod_url="http://localhost:4001",
        algod_token="a"*64
    )

    # 1. Fetch the SSE URL (if testing HTTP SSE directly)
    endpoint_url = "http://127.0.0.1:8001/sse/messages?session_id=..."
    
    # 2. Make an auto-paying request
    payload = {
        "jsonrpc": "2.0",
        "method": "tools/call",
        "params": {"name": "do_work", "arguments": {"premium": True}},
        "id": 1,
    }

    async with wrapHttpxWithPayment(x402_client, timeout=30) as c:
        resp = await c.post(endpoint_url, json=payload)
        print(f"Status: {resp.status_code}") # Will automatically handle the 402 and return 200 OK!

if __name__ == "__main__":
    asyncio.run(main())
```

## Subscriptions and Discounts

The SDK provides helper methods `has_active_subscription()` and `get_past_usage_amount()` out of the box to build complex tokenomics quickly. See the `examples/` directory for an implementation.

### Selling Subscriptions (Vending Machine)
You can instantly create a storefront for users to buy your subscription token using the `add_subscription_tool` helper. This natively handles Algorand's strict ASA opt-in requirements through a smart **Pre-flight check**:
1. If the user's wallet is not opted into your asset, the tool executes for free and returns instructions to opt-in.
2. If the user's wallet is opted in, the tool automatically charges them the ALGO price and transfers the token.

```python
# 1. (Optional) Mint a brand new token from your server wallet
# asset_id = sdk.mint_subscription_token("Pro Pass", "PRO", total_supply=1000)

# 2. Register the vending machine tool
sdk.add_subscription_tool(
    name="buy_pro_pass",
    description="Pay 1 ALGO to receive a Pro Pass subscription token.",
    price=1_000_000, # 1 ALGO
    asset_id=12345
)
```

Users can use the `ai_economy_sdk.utils.client_opt_in` utility to programmatically opt into your token before calling the buy tool:
```python
from ai_economy_sdk.utils import client_opt_in

# Opt-in to the asset (Costs standard 0.001 ALGO network fee)
client_opt_in(algod_client, client_pk, client_addr, asset_id=12345)
```
