agentpayy 1.0.2

AgentPayyKit Python SDK - Pay-per-call APIs for AI agents

AgentPayy Python SDK

Complete Python integration for the AgentPayy payment network. All features in one package.

Install

pip install agentpayy

Basic Usage

from agentpayy import AgentPayyKit

agentpay = AgentPayyKit(
    private_key="0x...", 
    chain="base"  # Uses deployed AgentPayy contracts
)

# Pay for API call
result = agentpay.call_api(
    "https://api.example.com",
    {"input": "data"},
    "model-id"
)

Complete Feature Set

Core Payment System

# Basic API payment
result = agentpay.call_api(endpoint, data, model_id)

# Payment validation (for API providers)
is_valid = agentpay.validate_payment(tx_hash, input_data)
agentpay.mark_validated(tx_hash)

Advanced Features

# Attribution payments (revenue sharing)
attributions = [
    {"recipient": "0xAgent1", "basisPoints": 6000},  # 60%
    {"recipient": "0xAgent2", "basisPoints": 4000}   # 40%
]

result = agentpay.pay_with_attribution(
    "complex-analysis",
    {"data": "input"},
    attributions,
    {"price": "0.10"}
)

# Balance management
agentpay.deposit_balance("10.0")  # Deposit $10 USDC
balance = agentpay.get_user_balance()
agentpay.withdraw_balance("5.0")  # Withdraw specific amount
agentpay.withdraw()  # Withdraw all earnings

# Reputation system
reputation = agentpay.get_reputation(agent_address)
specialists = agentpay.find_agents_by_specialty("weather-data", 4.0)
leaderboard = agentpay.get_leaderboard(10)

# API marketplace
agentpay.register_model({
    "modelId": "weather-api-v1",
    "endpoint": "https://api.myservice.com/weather",
    "price": "0.02",
    "category": "Weather & Environment"
})

weather_apis = agentpay.get_apis_by_category("Weather & Environment")

API Provider Integration

# Validate payments in your API
is_valid = agentpay.validate_payment(tx_hash, input_data)
if not is_valid:
    return {"error": "Invalid payment"}

# Mark payment as processed
agentpay.mark_validated(tx_hash)

# Register your API for monetization
agentpay.register_model({
    "modelId": "my-api",
    "endpoint": "https://api.myservice.com",
    "price": "0.05"
})

API Discovery & Marketplace

# Register API with full metadata
agentpay.register_model({
    "modelId": "weather-forecast-v2",
    "endpoint": "https://api.weather.com/forecast",
    "price": "0.03",
    "category": "Weather & Environment",
    "tags": ["weather", "forecast", "climate"],
    "description": "Advanced weather forecasting API"
})

# Discover APIs by category
weather_apis = agentpay.get_apis_by_category("Weather & Environment")

# Search APIs by tags
ai_apis = agentpay.search_apis_by_tag("ai")

# Get marketplace statistics
stats = agentpay.get_marketplace_stats()
print(f"{stats['totalAPIs']} APIs, {stats['totalDevelopers']} developers")

# Get trending APIs
trending = agentpay.get_trending_apis(10)

Available Networks

• base: Base mainnet (recommended)
• arbitrum: Arbitrum One
• optimism: Optimism mainnet
• polygon: Polygon mainnet

Key Features

• Complete Package: All AgentPayy features in single Python package
• Zero Setup: Uses deployed AgentPayy contracts (no deployment needed)
• Privacy-First: Only payment hashes stored on-chain
• Sub-Cent Costs: Enable $0.001-$0.01 API calls economically
• Multi-Chain: Works across Base, Arbitrum, Optimism L2s
• AI-Agent Ready: Perfect for CrewAI, AutoGPT, LangChain workflows
• FastAPI Integration: Built-in middleware for API monetization

Package Contents

• AgentPayyKit: Main payment class with all methods
• Reputation System: Agent discovery and scoring functions
• Attribution Engine: Multi-party revenue sharing
• Balance Management: Prepaid balance and earnings withdrawal
• API Registry: On-chain marketplace integration
• Crypto Utilities: Signature verification and hashing functions

Quick Start

from agentpayy import AgentPayyKit

# Initialize with private key
agentpay = AgentPayyKit(private_key="0x...", chain="base")

# Make API call with payment
result = agentpay.pay_and_call(
    model_id="weather-api",
    input_data={"city": "NYC"},
    price="0.01"
)
print(result)  # Weather data

Basic Usage

Initialize Client

import os
from agentpayy import AgentPayyKit

# From environment variable
agentpay = AgentPayyKit(
    private_key=os.getenv("PRIVATE_KEY"),
    chain="base",  # base|arbitrum|optimism|ethereum
    gateway_url="https://gateway.agentpayy.dev"
)

# Check connection
print(f"Wallet: {agentpay.account.address}")
print(f"Chain: {agentpay.chain}")

API Calls with Payment

# Simple API call
weather = agentpay.pay_and_call(
    model_id="weather-api",
    input_data={"city": "San Francisco"},
    price="0.01"
)

# With options
result = agentpay.pay_and_call(
    model_id="premium-analysis",
    input_data={"text": "Analyze this market data..."},
    price="0.25",
    use_balance=True,  # Try balance first
    mock=False         # Set True for testing
)

Mock Mode for Development

# Test without payment
mock_result = agentpay.pay_and_call(
    model_id="weather-api",
    input_data={"city": "Tokyo"},
    price="0.01",
    mock=True  # Returns realistic mock data
)

print(mock_result)  # {'temperature': 72, 'condition': 'sunny', 'mock': True}

Balance Management

Netflix-Style Prepaid Balance

# Deposit to balance
agentpay.deposit_balance(amount="10.0")  # $10 USDC

# Check balance
balance = agentpay.get_user_balance()
print(f"Balance: ${balance} USDC")

# Check if can afford API call
can_afford = agentpay.check_user_balance(required="0.05")

# Withdraw from balance
agentpay.withdraw_balance(amount="5.0")

API Provider Functions

Register API for Monetization

# Register your API to earn money
agentpay.register_model(
    model_id="my-analysis-api",
    endpoint="https://api.myservice.com/analyze",
    price="0.50"
)

# Check earnings
earnings = agentpay.get_earnings()
print(f"Earned: ${earnings} USDC")

# Withdraw earnings
tx_hash = agentpay.withdraw_earnings()
print(f"Withdrawal: {tx_hash}")

CrewAI Integration

from agentpayy.crewai import AgentPayyTool

# Create paywall tool for CrewAI agents
weather_tool = AgentPayyTool(
    model_id="weather-api",
    price="0.01",
    description="Get current weather for any city",
    chain="base"
)

# Use in CrewAI agent
from crewai import Agent

agent = Agent(
    role="Weather Analyst",
    goal="Provide weather insights",
    tools=[weather_tool]
)

# Agent automatically pays for API calls
result = agent.execute("What's the weather in NYC?")

LangChain Integration

from agentpayy.langchain import AgentPayyWrapper
from langchain.tools import Tool

# Wrap any API with payment
paid_weather_tool = Tool(
    name="Weather API",
    description="Get weather data with automatic payment",
    func=AgentPayyWrapper(
        model_id="weather-api",
        price="0.01",
        chain="base"
    )
)

# Use with LangChain agents
from langchain.agents import initialize_agent

agent = initialize_agent(
    tools=[paid_weather_tool],
    llm=your_llm,
    agent="zero-shot-react-description"
)

# Agent pays automatically when using the tool
response = agent.run("What's the weather like in London?")

FastAPI Integration

from fastapi import FastAPI
from agentpayy import require_payment

app = FastAPI()

@app.post("/premium-analysis")
@require_payment(model_id="analysis-api", price="0.25")
async def premium_analysis(data: dict):
    """Premium analysis endpoint with automatic payment"""
    # Payment is verified before this function runs
    return {"analysis": "Premium analysis results...", "paid": True}

# Clients automatically pay when calling this endpoint

Financial Overview

# Complete financial picture
financials = agentpay.get_financial_overview()

print(f"Earnings: ${financials['earnings']}")
print(f"Balance: ${financials['balance']}")  
print(f"Total Spent: ${financials['total_spent']}")
print(f"Net Position: ${financials['net_position']}")

Multi-Chain Usage

# Different chains for different use cases
base_client = AgentPayyKit(private_key=key, chain="base")        # Consumer apps
arbitrum_client = AgentPayyKit(private_key=key, chain="arbitrum") # DeFi integration
optimism_client = AgentPayyKit(private_key=key, chain="optimism") # Superchain apps

# Ethereum for enterprise
ethereum_client = AgentPayyKit(private_key=key, chain="ethereum")

Environment Setup

# Required
export PRIVATE_KEY="0x..."

# Optional - Smart wallet features
export BICONOMY_PAYMASTER_API_KEY="..."
export ZERODEV_API_KEY="..."

# Optional - Custom gateway
export AGENTPAY_GATEWAY_URL="https://gateway.agentpayy.dev"

Error Handling

from agentpayy.exceptions import InsufficientBalance, PaymentFailed

try:
    result = agentpay.pay_and_call("expensive-api", data, "10.0")
except InsufficientBalance:
    print("Need to deposit more funds")
    agentpay.deposit_balance("20.0")
    result = agentpay.pay_and_call("expensive-api", data, "10.0")
    
except PaymentFailed as e:
    print(f"Payment failed: {e}")
    # Try with mock mode for testing
    result = agentpay.pay_and_call("expensive-api", data, "10.0", mock=True)

Examples

AI Trading Bot

from agentpayy import AgentPayyKit
import time

class TradingBot:
    def __init__(self):
        self.agentpay = AgentPayyKit(
            private_key=os.getenv("PRIVATE_KEY"),
            chain="base"
        )
        
        # Register price alert service (earn money)
        self.agentpay.register_model(
            model_id="price-alerts",
            endpoint="https://bot.example.com/alerts",
            price="0.10"
        )
        
        # Deposit trading capital
        self.agentpay.deposit_balance("100.0")
    
    def trade(self):
        # Get market data (spend money)
        prices = self.agentpay.pay_and_call(
            model_id="market-data",
            input_data={"symbols": ["BTC", "ETH"]},
            price="0.02"
        )
        
        # Analyze and trade based on data
        if prices["BTC"] > 50000:
            # Send alerts to subscribers (earn money automatically)
            pass
    
    def run(self):
        while True:
            self.trade()
            time.sleep(60)

# Bot both earns and spends using same wallet
bot = TradingBot()
bot.run()

Data Pipeline

from agentpayy import AgentPayyKit

class DataPipeline:
    def __init__(self):
        self.agentpay = AgentPayyKit(
            private_key=os.getenv("PRIVATE_KEY"),
            chain="arbitrum"  # Lower costs for high volume
        )
    
    def process_data(self, raw_data):
        # Step 1: Clean data (pay for cleaning API)
        cleaned = self.agentpay.pay_and_call(
            "data-cleaning",
            {"data": raw_data},
            "0.01"
        )
        
        # Step 2: Analyze data (pay for analysis API)
        analysis = self.agentpay.pay_and_call(
            "data-analysis", 
            cleaned,
            "0.05"
        )
        
        # Step 3: Generate insights (pay for AI model)
        insights = self.agentpay.pay_and_call(
            "insight-generation",
            analysis,
            "0.10"
        )
        
        return insights

# Pay for each step in data pipeline
pipeline = DataPipeline()
results = pipeline.process_data(your_data)

Research Assistant

import asyncio
from agentpayy import AgentPayyKit

class ResearchAssistant:
    def __init__(self):
        self.agentpay = AgentPayyKit(
            private_key=os.getenv("PRIVATE_KEY"),
            chain="base"
        )
    
    async def research_topic(self, topic):
        tasks = [
            # Parallel API calls with payments
            self.agentpay.pay_and_call("news-api", {"query": topic}, "0.03"),
            self.agentpay.pay_and_call("academic-papers", {"topic": topic}, "0.05"),
            self.agentpay.pay_and_call("expert-opinions", {"subject": topic}, "0.08")
        ]
        
        results = await asyncio.gather(*tasks)
        
        # Synthesize results (another paid API)
        synthesis = self.agentpay.pay_and_call(
            "content-synthesis",
            {"sources": results},
            "0.15"
        )
        
        return synthesis

# Research assistant that pays for premium sources
assistant = ResearchAssistant()
research = asyncio.run(assistant.research_topic("AI safety"))

Convenience Functions

# Quick one-liner for simple use cases
from agentpayy import pay_and_call

# Uses PRIVATE_KEY from environment
result = pay_and_call(
    model_id="weather-api",
    input_data={"city": "NYC"},
    price="0.01",
    mock=True  # For testing
)

Support

• AI Frameworks: Native CrewAI and LangChain support
• Web3: Full smart contract integration
• Testing: Mock mode for development
• Multi-chain: 13 networks supported

See main repository for additional examples and integration guides.