Metadata-Version: 2.4
Name: ai-economy-sdk
Version: 0.1.3
Summary: Payment-gated MCP server SDK for Algorand
Author-email: AI Economy Team <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.1.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)
```

## 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.
