OPENAI AGENTS SDK INTEGRATION

OpenAI Agents SDK integration.

Add USDC payments to your OpenAI Agents SDK agents. One tool, native handoff support, structured-output compatible.

SHORT ANSWER

Blockchain0x provides a drop-in payment_request_tool for the OpenAI Agents SDK. Install blockchain0x-openai-agents, add the tool to your Agent's tools list, and the agent can request USDC payment for any work it does. Works with single agents, multi-agent handoffs, structured outputs, and the underlying Responses API. Payments settle on Base.

WHY OPENAI AGENTS SDK

The cleanest tool-calling surface OpenAI ships.

The OpenAI Agents SDK (released 2025) is OpenAI's recommended way to build agents on top of the Responses API. It abstracts the boilerplate around tool registration, message loops, and handoffs between agents, and it produces clean, typed Python code. If you are starting an OpenAI-centric agent project today and do not have framework preferences, this is the SDK we recommend.

Our integration is intentionally thin. payment_request_tool is a function tool in the SDK's standard format. You add it to an Agent's tools list. The Runner picks it up automatically. There is no special configuration, no extra Runner wrapper, no fork of the SDK. When the Agents SDK ships a new feature (multi-modal inputs, voice agents, etc.), our integration works because we ride on the standard tool-calling surface.

INSTALLATION

One pip install. Four environment variables.

Targets Python 3.10+ and the OpenAI Agents SDK 0.3+. The OpenAI Agents SDK itself is a peer dependency; install it separately if not already in your project.

INSTALL

pip install blockchain0x-openai-agents

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 is your existing OpenAI key (the Agents SDK uses it for the underlying Responses API). BLOCKCHAIN0X_API_KEY and BLOCKCHAIN0X_AGENT_ID come from the agent's settings page after 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 OpenAI Agents SDK setup with both payment_request_tool and refund_payment_tool registered. The agent's instructions tell it to request payment before doing work; the Runner orchestrates the tool calls automatically.

AGENT.PY

from agents import Agent, Runner
from blockchain0x.openai_agents import payment_request_tool, refund_payment_tool

agent = Agent(
    name="research-bot",
    instructions=(
        "You produce paid research reports for clients. "
        "Before doing any research, use payment_request_tool to request "
        "USDC payment. Hand the hosted_url to the client and end your turn. "
        "Wait for the webhook to trigger a follow-up run before delivering "
        "the actual report."
    ),
    tools=[payment_request_tool, refund_payment_tool],
    model="gpt-4o",
)

result = await Runner.run(
    agent,
    input="Write me a Q4 LLM market analysis. Charge me $5 USDC for it.",
)
print(result.final_output)

When the Runner runs this agent, the LLM reads the instructions, sees the dollar amount in the user's input, calls payment_request_tool, gets back a hosted_url, returns the URL to the user, and ends the turn. No research is produced yet; that happens in a follow-up run triggered by the webhook handler.

WEBHOOK HANDLING

Trigger a follow-up Runner.run when payment confirms.

Your webhook URL receives a signed POST when the chain confirms payment. The handler verifies the signature and triggers a follow-up Runner.run (or enqueues one) that delivers the paid work. FastAPI example below.

WEBHOOK.PY

from fastapi import FastAPI, Request, HTTPException
from blockchain0x.openai_agents 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":
        # Resume the agent with the confirmed payment context
        await resume_research_for(event["data"]["payment_request_id"])
    return {"ok": True}

verify_webhook does 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 Runner.run via an async job queue (Celery, arq, RQ) rather than inline in the webhook handler - Agents SDK runs over complex tasks can take several minutes and time out HTTP requests.

STARTER REPOSITORY

Working examples with single-agent and multi-agent handoffs.

A complete OpenAI Agents SDK repository at the GitHub link below. Includes a single-agent example (the one above), a multi-agent handoff example (triage agent that bills + delegates to researcher/writer/reviewer), a FastAPI webhook handler, and a docker-compose orchestrating the agent service, webhook server, and a Redis queue.

github.com/blockchain0x/agent-wallet-openai-agents

Repository structure: single_agent.py, multi_agent.py (with handoffs), webhook.py, docker-compose.yml, README walking through Base mainnet deployment and Base Sepolia testing.

COMMON PITFALLS

Five things to watch on first integration.

These come from our support inbox. Knowing them in advance saves an hour each.

PITFALL 1

Confusing Agents SDK with the Assistants API

The OpenAI Agents SDK (released 2025) and the older Assistants API are different products. The Agents SDK is what this integration targets: it uses the Responses API under the hood, supports handoffs between agents, and has a clean Python interface. The Assistants API is the older threads/runs model that OpenAI is sunsetting. If you import 'from openai import OpenAI' and call client.beta.assistants.create(...), you are on the old API; the blockchain0x.openai_agents wrapper will not work. Switch to the Agents SDK first.

PITFALL 2

Handoff loops

Agents SDK supports handoffs - an agent can transfer control to another agent. If you put the payment_request_tool on the wrong agent in a handoff chain, the agent might hand off to a downstream agent that then tries to use the payment tool it does not have. The cleanest pattern: keep payment on the front-facing agent that talks to the user, never delegate it. Downstream agents do work; the front agent handles billing.

PITFALL 3

Tool result truncation in the Responses API

The Responses API truncates tool outputs above a certain size. payment_request_tool's response is well under the limit, but if you wrap it with extra metadata (logging, audit trail), the wrapped result can grow. Keep the tool's returned value minimal; the SDK returns just the hosted_url and the payment_request_id by default, which is what the LLM needs to surface to the user.

PITFALL 4

Model selection and tool-call behavior

Tool calling behaves differently across OpenAI models. gpt-4o, gpt-4o-mini, and o1-mini all call tools reliably. o3-mini and o3 are more conservative and sometimes refuse to call tools without explicit instructions. If your agent ignores the payment tool, try adding 'You MUST use payment_request_tool before doing any work' to instructions and confirm the model is gpt-4o or later.

PITFALL 5

Async-only runtime

The Agents SDK is async-only. Runner.run is awaitable. Calling Runner.run_sync exists but doesn't work properly with the Blockchain0x SDK's async HTTP client; you get partial results and missing payment requests. Always use the async path (asyncio.run() at the top level if you need to call from a sync context).

FREQUENTLY ASKED

Three OpenAI Agents SDK questions.

Does this work with multi-agent handoffs?

Yes, but you need to think about which agent owns billing. The recommended pattern is to keep the payment_request_tool on a single front-facing agent (the one the user first talks to) and have that agent delegate the actual work to specialist agents after payment confirms. The specialist agents do not have the payment tool, so there is no risk of double-charging or wrong-agent charging. The starter repo includes a multi-agent example showing this pattern with a triage agent that bills + delegates to research, writing, and review agents.

Can I use this with the OpenAI Responses API directly, without the Agents SDK?

Yes. The Responses API exposes the same tool-calling capability that the Agents SDK builds on. If you are calling client.responses.create() directly, register payment_request_tool as a function tool in your tool list (the SDK exposes the OpenAPI-style schema via payment_request_tool.to_responses_tool()). This is more work than using the Agents SDK directly; the Agents SDK is the path of least resistance.

How does this work with structured outputs?

The Agents SDK's structured output feature (Pydantic models as the agent's response type) is fully compatible. payment_request_tool returns a typed PaymentRequest object that you can reference in your structured output schema. The pattern: define a response model that includes a payment_url field, populate it from the tool's return value, and the LLM produces structured output containing the hosted URL. This is the cleanest UX for agents that need to surface payment requirements as part of their normal response.

All integrations Pricing

Add payments to your Agents SDK build.

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