Skip to main content
AGNO INTEGRATION

Agno payment integration.

Add USDC payments to any Agno agent. Drop-in tool, lightweight Python-native, minimal abstraction overhead.

SHORT ANSWER

Blockchain0x provides drop-in PaymentRequestTool and RefundPaymentTool classes for Agno agents. Install blockchain0x-agno, instantiate the tools, add them to your Agent's tools list, and the agent can request and refund USDC payments. Works with all Agno models (OpenAI, Anthropic, DeepSeek, Llama, Mistral). Payments settle on Base; webhooks confirm.

WHY AGNO

The lightweight Python framework. No abstraction tax.

Agno (formerly Phidata) is the agent framework you reach for when you want minimal ceremony. There is no Graph builder, no Crew, no Workflow - just Agent, Tools, and a run() method. Tools are Python callables. The framework adds enough scaffolding to call LLMs with tool support, manage memory, and produce streaming output, then gets out of your way.

Our integration follows the same philosophy. PaymentRequestTool is a Python class that inherits from Agno's Toolkit. It looks and behaves like every other Agno tool. There is no special setup beyond instantiation, no graph to wire up, no orchestration to define. The simplicity is the point - if you wanted graphs you would be on LangGraph.

INSTALLATION

One pip install. Four environment variables.

Targets Python 3.10+ and Agno 1.0+ (which includes the rename from Phidata). If you are still on phi.* imports, run pip install -U agno first.

INSTALL
pip install blockchain0x-agno
ENVIRONMENT VARIABLES
export OPENAI_API_KEY=sk-...
export BLOCKCHAIN0X_API_KEY=sk_live_...
export BLOCKCHAIN0X_AGENT_ID=agt_abc123
export BLOCKCHAIN0X_SIGNING_SECRET=whsec_...

OPENAI_API_KEY (or the equivalent for whichever Agno-supported model you use). BLOCKCHAIN0X_API_KEY and BLOCKCHAIN0X_AGENT_ID come from the agent's settings page in the Blockchain0x dashboard after agent creation. BLOCKCHAIN0X_SIGNING_SECRET is needed only in the process that handles webhooks.

FULL AGENT EXAMPLE

A research agent with payment + refund tools.

Below is a complete Agno agent with PaymentRequestTool and RefundPaymentTool registered. The instructions tell the agent to charge before working; the run() call orchestrates the tool invocations.

AGENT.PY
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from blockchain0x.agno import PaymentRequestTool, RefundPaymentTool

agent = Agent(
    name="research-bot",
    model=OpenAIChat(id="gpt-4o"),
    tools=[
        PaymentRequestTool(),
        RefundPaymentTool(),
        # ... your other tools
    ],
    instructions=[
        "You produce paid research reports.",
        "Before doing any research, use payment_request_tool to charge",
        "the client. Surface the hosted_url and end your turn.",
        "Wait for the webhook to trigger a follow-up run before delivering.",
    ],
    markdown=True,
)

result = agent.run(
    "Write me a Q4 LLM market analysis. Charge me $5 USDC for it."
)
print(result.content)

When agent.run() executes, the LLM reads the instructions, parses the $5 from the user message, calls PaymentRequestTool, gets back a hosted_url, surfaces it as part of its response, and ends the turn. The actual research happens later in a follow-up run triggered by the webhook handler.

WEBHOOK HANDLING

FastAPI handler that resumes the work after payment.

The webhook URL receives a signed POST when the chain confirms payment. Verify the signature, then trigger a fresh agent.run (or enqueue one) to deliver the paid work. FastAPI example below.

WEBHOOK.PY
from fastapi import FastAPI, Request, HTTPException
from blockchain0x.agno import verify_webhook
import os

app = FastAPI()
SIGNING_SECRET = os.environ["BLOCKCHAIN0X_SIGNING_SECRET"]

@app.post("/webhooks/payment")
async def receive(request: Request):
    signature = request.headers.get("X-Blockchain0x-Signature", "")
    body = await request.body()
    if not verify_webhook(body, signature, SIGNING_SECRET):
        raise HTTPException(status_code=401)

    event = await request.json()
    if event["type"] == "payment.confirmed":
        await deliver_research_for(event["data"]["payment_request_id"])
    return {"ok": True}

verify_webhook uses HMAC-SHA256 in constant time. Read the raw body via await request.body(); do not call request.json() then re-serialize, because that destroys the signature. Run the follow-up agent.run inside a Celery or arq job, not inline in the webhook handler - Agno runs that hit reasoning models or do long retrieval can take 30+ seconds and time out HTTP requests.

STARTER REPOSITORY

Working examples with single agent + Teams.

A complete Agno repository at the GitHub link below. Includes the single-agent example, a 3-agent Team variant (biller + researcher + reviewer), a streaming-mode example for reasoning models, a FastAPI webhook handler with Redis queue, and a docker-compose orchestrating the agent + webhook + queue + AgentUI.

github.com/blockchain0x/agent-wallet-agno

Repository structure: agent.py (single agent), team.py (3-agent Team), reasoning_streaming.py (streaming example for o1/DeepSeek R1), webhook.py (FastAPI), agentui-config.py (AgentUI integration), docker-compose.yml, README with notes on Modal, Fly.io, and Replit deployment.

COMMON PITFALLS

Five Agno-specific things to watch.

Agno is one of the cleaner agent frameworks to integrate with, but it has its own gotchas - especially around the Phidata renaming and markdown rendering.

PITFALL 1

Phidata -> Agno migration confusion

Agno was renamed from Phidata in 2024. If you have an older codebase importing from phi.agent or phi.tools, those imports still work via a compatibility shim but the new agno.* imports are recommended. Our integration ships only the agno.* API; if your code is still on phi.* imports, upgrade Agno itself first (pip install -U agno) before adding our tools.

PITFALL 2

Tool initialization order

Agno's Agent constructor instantiates tools immediately. PaymentRequestTool() reads env vars at construction time (BLOCKCHAIN0X_API_KEY, BLOCKCHAIN0X_AGENT_ID). If you set those env vars after constructing the Agent, the tool has stale values. Set env vars at process start (or pass them explicitly to PaymentRequestTool(api_key=..., agent_id=...)) to avoid surprises.

PITFALL 3

Sync vs async run

Agno supports agent.run() (sync) and agent.arun() (async). Our tools are async-native under the hood but expose both shapes. If you mix - call agent.run() but try to await the result - you get a coroutine where you expected a string. Pick one mode per agent. For long-running graphs with multiple agents, async is usually cleaner.

PITFALL 4

Markdown rendering swallows the hosted URL

If you have markdown=True on the Agent (the default for nice chat output), the LLM may render the payment URL inside Markdown formatting like [link](url) or even an HTML <a> tag. Downstream code that expects a bare URL needs to either set markdown=False, or parse the structured response.tool_calls to get the raw payment_request_id. The starter repo has a helper that does this parsing.

PITFALL 5

Memory/storage with paid agents

Agno's persistent memory (PostgresMemory, SqliteMemory) records the agent's conversation history including tool calls. For paid agents, this is good - you have an audit trail of every payment request. But the storage by default includes the full tool result, including any sensitive customer info embedded in the reason string. Either redact reason at write time or use a dedicated storage table with PII-scrubbing enabled.

FREQUENTLY ASKED

Three Agno-specific questions.

Does this work with Agno Teams (multi-agent collaboration)?

Yes. Agno Teams combine multiple Agents into a single coordinated unit. Our tools work in any agent that lists them in its tools list, including agents inside a Team. The recommended pattern for Teams is to put PaymentRequestTool on one dedicated billing agent and let the other team members handle work after payment confirms - same shape as our CrewAI integration. The starter repo includes a 3-agent Team example with biller + researcher + reviewer roles.

How does this interact with Agno's reasoning models (o1, DeepSeek R1)?

Reasoning models work fine. The only thing to know: reasoning models are slower per turn, so the request-then-end-turn pattern adds a noticeable pause before the user sees the payment URL. Mitigate by streaming the partial response so the user sees 'I will request payment now...' before the tool call completes. Agno's streaming support handles this; see the starter repo for the streaming example.

Can I use the AgentUI to visualize paid runs?

Yes. AgentUI is Agno's web UI for inspecting agent runs. Paid runs show up like any other run, with the payment_request tool call visible in the tool-calls panel. The hosted_url is rendered inline so you can click straight through to test the payment flow during development. AgentUI does not yet have native payment-flow widgets (a sale graph, a refund button), but those work as standard tool calls in the UI.
All integrations Pricing

Charge for your Agno agent's work.

Five minutes from pip install to your first paid Agno run. Pro at $9/agent/month.