Skip to main content

Python SDK

The Walleot Python SDK enables you to integrate payment functionality into your MCP (Model Context Protocol) servers. This guide covers installation, initialization, pricing tools, and payment coordination modes.

Installation​

pip install walleot

Quick Start​

Here's how to get started with the Python SDK in an MCP server:

from mcp.server.fastmcp import FastMCP, Context
from walleot import Walleot, Mode
import os

# Initialize your MCP server
mcp = FastMCP("My AI agent")

# Initialize Walleot with your API key
Walleot(
    mcp,
    apiKey=os.getenv("WALLEOT_API_KEY")
)

# Define a priced tool
@mcp.tool()
@Walleot.price(0.19, currency="USD")  # $0.19 per call
def add_numbers(a: int, b: int, ctx: Context) -> int:
    """Adds two numbers and returns the sum."""
    return a + b

API Reference​

Walleot Class​

The main class for integrating Walleot with your MCP server.

Constructor​

Walleot(
    mcp_server: FastMCP,
    apiKey: str,
    mode: Mode = Mode.TWO_STEP # Mode.RESUBMIT / Mode.ELICITATION / Mode.PROGRESS / Mode.DYNAMIC_TOOLS
)

Parameters:

  • mcp_server: Your FastMCP server instance
  • apiKey: Your Walleot API key (get from dashboard)
  • mode: Payment coordination mode (see Mode enum below)

Mode Enum​

Controls how your MCP Server and the MCP client coordinate the payment process.

from walleot import Mode

# Available options:
Mode.TWO_STEP       # Default
Mode.RESUBMIT
Mode.ELICITATION   
Mode.PROGRESS
Mode.DYNAMIC_TOOLS

Pricing Decorator​

Use the @Walleot.price() decorator to set per-call pricing on your MCP tools:

@mcp.tool()
@Walleot.price(amount, currency="USD")
def your_tool(param1: str, param2: int, ctx: Context):
    """Your tool description."""
    # Tool implementation
    pass

Parameters:

  • amount: Price in dollars (e.g., 0.19 = $0.19)
  • currency: Currency code (default: "USD")

Examples​

Basic Math Tool​

from mcp.server.fastmcp import FastMCP, Context
from walleot import Walleot, Mode

mcp = FastMCP("Calculator")

Walleot(mcp, apiKey=os.getenv("WALLEOT_API_KEY"))

@mcp.tool()
@Walleot.price(0.10, currency="USD")  # $0.10 per calculation
def calculate(a: float, b: float, operation: str, ctx: Context) -> float:
    """Performs basic math operations."""
    if operation == "add":
        return a + b
    elif operation == "subtract":
        return a - b
    elif operation == "multiply":
        return a * b
    elif operation == "divide":
        return a / b if b != 0 else 0
    else:
        raise ValueError("Invalid operation")

Image Generation Tool​

from mcp.server.fastmcp import FastMCP, Image, Context
from walleot import Walleot, Mode
import base64
from io import BytesIO
from PIL import Image as PILImage

mcp = FastMCP("Image Generator")

Walleot(mcp, apiKey=os.getenv("WALLEOT_API_KEY"))

@mcp.tool()
@Walleot.price(0.50, currency="USD")  # $0.50 per image
async def generate_image(prompt: str, ctx: Context) -> Image:
    """Generates an image from a text prompt."""
    # Your image generation logic here
    # Return as MCP Image resource
    pass

Environment Setup​

Required Environment Variables​

# .env file
WALLEOT_API_KEY=your_api_key_here

Loading Environment Variables​

import os
from dotenv import load_dotenv

# Load .env file in development
load_dotenv()

# Access API key
api_key = os.getenv("WALLEOT_API_KEY")

Best Practices​

  1. Always use the Context parameter: Include ctx: Context in your tool signatures
  2. Set appropriate prices: Consider the computational cost and value of your tools
  3. Handle errors gracefully: Implement proper error handling in your tools
  4. Use environment variables: Never hardcode API keys
  5. Test payment flows: Verify your payment flows work as expected

Next Steps​