# Microtoll — Complete Documentation

> Pay-per-use API gateway for AI agents. One wallet, all APIs.

Microtoll is a pay-per-use API gateway for AI agents. Instead of managing separate API keys and subscriptions for every service, your agent accesses paid APIs through a single MCP server — web search, transcription, image generation, LLMs, and more.

---

## 1. What is Microtoll?

Microtoll is a pay-per-use API gateway for AI agents. Instead of managing separate API keys and subscriptions for every service, your agent accesses paid APIs through a single MCP server — web search, transcription, image generation, LLMs, and more.

You only pay for what you use. No monthly subscriptions, no per-API signups. One wallet, all APIs.

### How it works

1. Your agent calls an API through the Microtoll proxy
2. The proxy returns HTTP 402 with a Spark invoice (cost in sats)
3. Your SDK pays the invoice automatically
4. The proxy forwards the request to the upstream API
5. The response is returned to your agent
6. If the upstream API fails (429, 5xx), a credit token is issued (valid 7 days)

### Available API categories

Web search, transcription, text-to-speech, image generation, video generation, LLMs, embeddings, financial data, translation, and more. Browse all at: https://microtoll.io/discover

---

## 2. Wallet Setup

## Step 1: Set up your wallet

Microtoll payments use Spark — a Bitcoin layer that enables instant, near-zero-fee micropayments. Think of it like a prepaid balance: you load funds once, and your agent spends fractions of a cent per API call.

```bash
pip install microtoll-mcp
microtoll setup
# Choose option 1 (Spark wallet)
export SPARK_MNEMONIC="your 24 words here"
```

Fund your wallet with a few dollars:

**I've never used crypto before**

- Run: `microtoll fund --lightning 5000` (generates a Lightning invoice for 5000 sats ≈ $5)

- Sign up and buy $5-10 of Bitcoin on one of these services:
  - **Strike** (strike.me) — US, EU, UK, 65+ countries — credit/debit card
  - **Cash App** (cash.app) — US only — debit card
  - **Mt Pelerin** (mtpelerin.com) — 171 countries, no KYC under $200 — credit/debit card
  - **Coinbase** (coinbase.com) — 100+ countries — credit/debit card

- In the app, go to Send/Withdraw → paste the Lightning invoice from step 1 → confirm — done!


**I have USDC (Solana, Base, or Arbitrum)**

- Get your Spark address: `microtoll fund --show-address`

- Go to joltz.io — paste your address and send USDC


**I already have a Lightning wallet (Phoenix, Alby, Strike, Cash App...)**

- Run: `microtoll fund --lightning 1000` (to receive 1000 sats)

- Pay the displayed invoice from your wallet — done!


---

## 3. MCP Server (Recommended for agent frameworks)

The MCP server is the simplest way to give your agent access to Microtoll APIs.

### Install

```bash
pip install microtoll-mcp
# or use without installing:
uvx microtoll-mcp
```

### Available MCP tools

| Tool | Description |
|------|-------------|
| `search_apis` | Discover APIs with pricing and health status |
| `estimate_cost` | Check the price before paying |
| `call_api` | Call any API — payment is automatic |
| `get_wallet_status` | Check wallet balance and credits |
| `get_spending_history` | View spending history and summary |
| `check_health` | Check API health before calling (free) |
| `request_api` | Request a new API to be added |
| `identify_consumer` | Register for Travel Rule compliance (one-time) |

### Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `SPARK_MNEMONIC` | Yes | Your 24-word wallet mnemonic |
| `MICROTOLL_CONSUMER_TOKEN` | No | Token from consumer registration (for Travel Rule services) |
| `MICROTOLL_API_URL` | No | API URL (default: https://api.microtoll.io) |
| `MICROTOLL_MAX_COST_SATS` | No | Max cost per call in sats (safety limit) |

---

## 4. Python SDK

### Install

```bash
pip install microtoll
```

### Basic usage

```python
from microtoll import Microtoll

async with Microtoll() as m:
    # Search for APIs
    apis = await m.search("web search")

    # Estimate cost before calling
    estimate = await m.estimate("tavily", "/search", {"query": "test"})
    print(f"Cost: {estimate.cost_sats} sats")

    # Call an API (payment is automatic)
    result = await m.call("tavily", "/search", {"query": "AI agents 2026"})
    print(result.data)

    # Check wallet balance
    status = await m.wallet_status()
    print(f"Balance: {status.balance_sats} sats")
```

### Error handling

```python
from microtoll import (
    Microtoll,
    PaymentRequired,     # HTTP 402 — need payment
    CostTooHigh,         # Cost exceeds max_cost_sats
    BudgetExceeded,      # Session budget exceeded
    RetryExhausted,      # Max retries reached
    PaymentFailed,       # Wallet payment failed
)
```

---

## 5. TypeScript SDK

### Install

```bash
npm install microtoll
```

### Basic usage

```typescript
import { Microtoll } from "microtoll";

const m = new Microtoll();

// Call an API
const result = await m.call("tavily", "/search", { query: "AI agents 2026" });
console.log(result.data);

// Check wallet
const status = await m.walletStatus();
console.log(`Balance: ${status.balanceSats} sats`);

m.close();
```

---

## 6. Consumer Registration (Travel Rule)

Some APIs require consumer identification (Travel Rule compliance). This is a one-time process:

```bash
# Step 1: Submit identification
curl -X POST https://api.microtoll.io/consumer/identify \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "name": "Your Name"}'

# Step 2: Verify email (check inbox for code)
curl -X POST https://api.microtoll.io/consumer/verify-email \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "code": "123456"}'
# Returns: {"consumer_token": "mct_..."}

# Step 3: Set the token
export MICROTOLL_CONSUMER_TOKEN="mct_..."
```

Or visit: https://microtoll.io/identify

---

## 7. API Discovery

### Via MCP

Use the `search_apis` tool to find APIs by keyword.

### Via Registry API

```bash
# Search APIs
curl https://api.microtoll.io/registry/search?q=web+search

# Get service details
curl https://api.microtoll.io/registry/services/tavily

# List categories
curl https://api.microtoll.io/registry/categories
```

### Via Web

Browse all available APIs at: https://microtoll.io/discover

---

## 8. Framework Integration Guides

### CrewAI

CrewAI supports MCP tools natively since v0.100+.

Add Microtoll as an MCP server in your crew configuration.

```python
# crewai.yaml or in Python:
from crewai import Agent, Crew, Task
from crewai.tools import MCPServerAdapter

microtoll = MCPServerAdapter(
    server_params={
        "command": "uvx",
        "args": ["microtoll-mcp"],
        "env": {
            "SPARK_MNEMONIC": "your-24-word-mnemonic",
            "MICROTOLL_CONSUMER_TOKEN": "mct_...",  # optional, for Travel Rule services
        },
    }
)

researcher = Agent(
    role="Web Researcher",
    goal="Find accurate, up-to-date information",
    tools=[microtoll],
)

task = Task(
    description="Search for the latest AI agent frameworks in 2026",
    agent=researcher,
)

crew = Crew(agents=[researcher], tasks=[task])
result = crew.kickoff()
```

### LangChain / LangGraph

LangChain supports MCP tools via langchain-mcp-adapters.

Install the adapter and connect Microtoll as a tool provider.

```python
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI

async with MultiServerMCPClient({
    "microtoll": {
        "command": "uvx",
        "args": ["microtoll-mcp"],
        "env": {
            "SPARK_MNEMONIC": "your-24-word-mnemonic",
            "MICROTOLL_CONSUMER_TOKEN": "mct_...",  # optional, for Travel Rule services
        },
    }
}) as client:
    tools = client.get_tools()
    agent = create_react_agent(
        ChatOpenAI(model="gpt-4o"),
        tools,
    )
    result = await agent.ainvoke({
        "messages": "Search the web for AI agent payment solutions"
    })
```

### Cursor

Cursor supports MCP servers natively via .cursor/mcp.json.

Add Microtoll to your project or global configuration.

```json
// .cursor/mcp.json
{
  "mcpServers": {
    "microtoll": {
      "command": "uvx",
      "args": ["microtoll-mcp"],
      "env": {
        "SPARK_MNEMONIC": "your-24-word-mnemonic",
        "MICROTOLL_CONSUMER_TOKEN": "mct_..."
      }
    }
  }
}

// Then in Cursor agent mode, ask:
// "Search the web for the latest React 19 features using Tavily"
// Cursor will automatically use the Microtoll MCP tools.
```

### OpenAI Agents SDK

OpenAI Agents SDK supports MCP servers natively.

Register Microtoll as an MCP server in your agent configuration.

```python
from agents import Agent
from agents.mcp import MCPServerStdio

microtoll = MCPServerStdio(
    command="uvx",
    args=["microtoll-mcp"],
    env={"SPARK_MNEMONIC": "your-24-word-mnemonic"},
)

agent = Agent(
    name="Researcher",
    instructions="Use Microtoll tools to search the web and analyze data.",
    mcp_servers=[microtoll],
)

# The agent can now call search_apis, call_api, estimate_cost, etc.
from agents import Runner
result = await Runner.run(
    agent,
    "Search for the latest AI payment solutions using Tavily"
)
```

### LlamaIndex

LlamaIndex supports MCP tools via llama-index-tools-mcp.

Connect Microtoll as an MCP tool provider.

```python
from llama_index.tools.mcp import BasicMCPClient, McpToolSpec
from llama_index.agent.openai import OpenAIAgent

mcp_client = BasicMCPClient(
    command="uvx",
    args=["microtoll-mcp"],
    env={"SPARK_MNEMONIC": "your-24-word-mnemonic"},
)
mcp_tool_spec = McpToolSpec(client=mcp_client)
tools = await mcp_tool_spec.to_tool_list_async()

agent = OpenAIAgent.from_tools(tools, verbose=True)
response = agent.chat(
    "Search the web for LlamaIndex vs LangChain comparison"
)
```

### AutoGen

AutoGen (ag2) supports MCP tools natively.

Register Microtoll as an MCP server for your agents.

```python
from autogen_ext.tools.mcp import StdioServerParams, mcp_server_tools

server_params = StdioServerParams(
    command="uvx",
    args=["microtoll-mcp"],
    env={"SPARK_MNEMONIC": "your-24-word-mnemonic"},
)

tools = await mcp_server_tools(server_params)

# Use tools with AutoGen agents
from autogen_agentchat.agents import AssistantAgent

agent = AssistantAgent(
    name="researcher",
    model_client=model_client,
    tools=tools,
    system_message="Use Microtoll tools to search and call APIs.",
)
```

### Haystack

Haystack supports MCP tools via haystack-experimental.

Add Microtoll as a tool provider in your pipeline.

```python
from haystack_experimental.components.tools.mcp import (
    MCPClientTool, StdioClientTransport
)

transport = StdioClientTransport(
    command="uvx",
    args=["microtoll-mcp"],
    env={"SPARK_MNEMONIC": "your-24-word-mnemonic"},
)

# Create tools from MCP server
tools = await MCPClientTool.from_server(transport)

# Use in a Haystack pipeline with ToolInvoker
from haystack.components.agents import Agent
agent = Agent(tools=tools, chat_generator=generator)
result = agent.run(
    messages=[{"role": "user", "content": "Search the web for Haystack vs LangChain"}]
)
```

### Claude Code

Claude Code supports MCP servers natively via .mcp.json.

Add Microtoll to your project configuration.

```json
// .mcp.json (in your project root)
{
  "mcpServers": {
    "microtoll": {
      "command": "uvx",
      "args": ["microtoll-mcp"],
      "env": {
        "SPARK_MNEMONIC": "your-24-word-mnemonic",
        "MICROTOLL_CONSUMER_TOKEN": "mct_..."
      }
    }
  }
}

// Then in Claude Code, ask:
// "Search the web for the latest Python 3.14 features using the search_apis tool"
// Claude will discover and call the API through Microtoll.
```

---

## 9. CLI Reference

```bash
microtoll setup              # Interactive wallet setup wizard
microtoll wallet             # Show wallet balance and backend info
microtoll fund               # Show all funding options
microtoll fund --lightning N # Generate Lightning invoice to receive N sats
microtoll fund --show-address# Show Spark address for deposits/bridges
```

---

## 10. Pricing

Each API endpoint has its own pricing. Costs typically range from fractions of a cent to a few cents per call. Use `estimate_cost()` or the `estimate_cost` MCP tool to check prices before calling.

Pricing is displayed in sats (1 sat ≈ $0.001). Your wallet balance is deducted automatically.

Browse pricing for all APIs at: https://microtoll.io/discover