autogen-payclaw

Give your Microsoft AutoGen AssistantAgent a USDC wallet on Base it can actually spend. Gasless via Circle Paymaster. No ETH required. 1% flat fee. No KYC.

autogen-payclaw ships three production-grade tool functions for Microsoft AutoGen (v0.4+) that let any AssistantAgent read its USDC balance, send USDC to any address on Base mainnet, and inspect on-chain transaction history.

Built async-native to match AutoGen 0.4's event-driven model. Works as plain function tools (idiomatic AutoGen) or pre-wrapped FunctionTool instances.

---

Install

# Core (just the tool functions + HTTP client)
pip install autogen-payclaw

# Plus AgentChat + OpenAI client (for the quickstart below)
pip install "autogen-payclaw[agentchat]"

Auth

Set your PayClaw API token in the environment:

export PAYCLAW_API_TOKEN="..."

Or use PayClawClient directly with an explicit token.

Need a token? Each PayClaw wallet ships with its own Bearer token. The current public POC uses a single shared demo token — production replaces this with per-user OAuth. See payclaw.me.

---

Quickstart — pass functions directly to AssistantAgent

import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.ui import Console
from autogen_ext.models.openai import OpenAIChatCompletionClient

from autogen_payclaw import (
    payclaw_get_balance,
    payclaw_pay,
    payclaw_get_history,
)


async def main() -> None:
    model_client = OpenAIChatCompletionClient(model="gpt-4o-mini")

    agent = AssistantAgent(
        name="treasurer",
        model_client=model_client,
        tools=[payclaw_get_balance, payclaw_pay, payclaw_get_history],
        system_message=(
            "You are a payments agent operating on Base mainnet. "
            "You manage a USDC wallet you can read from and spend from. "
            "Before any transfer, restate the recipient and amount. "
            "After any transfer, surface the Basescan explorer URL as proof. "
            "Never invent addresses. If unsure, ask."
        ),
        reflect_on_tool_use=True,
    )

    await Console(agent.run_stream(
        task="Check my balance, then send 0.05 USDC to "
             "0x000000000000000000000000000000000000dEaD."
    ))

    await model_client.close()


asyncio.run(main())

Pre-wrapped FunctionTool instances

If you prefer explicit tool registration (with custom names or descriptions), use the pre-wrapped instances:

from autogen_payclaw import balance_tool, pay_tool, history_tool

agent = AssistantAgent(
    name="treasurer",
    model_client=model_client,
    tools=[balance_tool, pay_tool, history_tool],
)

Direct client (no AutoGen)

Use PayClawClient if you want the raw async HTTP interface:

import asyncio
from autogen_payclaw import PayClawClient

async def main():
    client = PayClawClient()  # reads PAYCLAW_API_TOKEN
    print(await client.get_balance())
    receipt = await client.pay(to="0x...", amount="0.05")
    print(receipt["txHash"])

asyncio.run(main())

---

The tools

payclaw_get_balance() -> str

Read-only. Returns a JSON string:

{
  "address": "0x567849BBEB2da9475F3EB0871Ad7C4CeA8738740",
  "signerAddress": "0x7371d193516BAb191fE99d7149Ed47f8bCBd42f7",
  "usdc": "2.01",
  "usdcRaw": "2010000",
  "chain": "base-mainnet",
  "explorer": "https://basescan.org/address/0x567849..."
}

payclaw_pay(to: str, amount: str) -> str

Sends USDC. Args: to (0x address), amount (decimal string, min "0.01").

{
  "txHash": "0xa36a...4528",
  "status": "confirmed",
  "amountSent": "0.05",
  "feeCharged": "0.0005",
  "gasPaidInUsdc": "0.0123",
  "smartAccountAddress": "0x567849...",
  "explorer": "https://basescan.org/tx/0xa36a...4528"
}

The first send from a new wallet auto-deploys the smart account on-chain (adds ~20-30 s to the first call). All gas is paid in USDC via Circle Paymaster. No ETH is ever required.

payclaw_get_history(limit: int = 10) -> str

Read-only. Optional limit (1-50, default 10). Returns the last ~28 hours of in/out USDC transfers touching the wallet.

---

Why PayClaw

Every existing way to give an AutoGen agent a wallet has the same defect: it needs ETH for gas. So you end up running an ETH-funding cron, or you bail and use a custodial API and lose the whole point of agent-owned funds.

PayClaw uses ERC-4337 v0.7 + Circle Paymaster: the agent's smart account spends USDC and the paymaster pays the bundler in USDC on its behalf. Your agent only ever holds and spends one asset.

	Agent wallet (vanilla)	Custodial API	PayClaw
Holds its own funds	✅	❌	✅
Needs ETH for gas	❌	n/a	✅
KYC required	❌	✅	❌
1 line to integrate	❌	❌	✅

---

Errors

Tool functions catch PayClawError and return a string the LLM can reason about — input-validation errors are also returned as strings prefixed with PayClaw input error: so the agent can correct itself rather than crash. Status codes:

• 400 — bad input (invalid address, amount below dust threshold)
• 401 — invalid bearer token
• 429 — rate-limited (only on first deploy from an empty wallet — fund the wallet to bypass)
• 502 — paymaster or RPC failure

If you want to handle errors yourself, drop down to PayClawClient and catch PayClawError directly.

---

Compatibility

• Python ≥ 3.10
• autogen-core >= 0.4.0 (required)
• autogen-agentchat >= 0.4.0 (optional, install via [agentchat] extra)
• pydantic >= 2.7
• httpx >= 0.27

License

MIT — see LICENSE.

Links

• Website: https://payclaw.me
• LangChain version: langchain-payclaw
• CrewAI version: crewai-payclaw
• SDK + MCP: https://github.com/ONSARI/payclaw-skill
• Issues: https://github.com/ONSARI/payclaw-skill/issues