ai-economy-sdk 0.1.0

A FastAPI/MCP integration for Algorand x402 payment gating.

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

Because this SDK relies on advanced AVM extensions for the x402 protocol, you must install both packages:

pip install x402-algorand ai-economy-sdk

Quickstart

import uvicorn
from algosdk import account, mnemonic
from ai_economy_sdk import AIEconomySDK

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

class MyAvmSigner:
    # See examples/ for a full implementation of AvmSigner
    pass

signer = MyAvmSigner(server_pk)

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

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