Skip to main content
OPENAI AGENTS SDK INTEGRATION

OpenAI Agents SDK integration.

There is no Agents SDK package, and you do not need one. Decorate a function with @function_tool, call the real blockchain0x client, and your agent can move USDC on Base.

SHORT ANSWER

There is no OpenAI Agents SDK package, and you do not need one. The SDK turns a decorated function into a tool with , so you wrap the real Python client in a function and add it to your . The agent can send USDC, settle invoices, and read wallets - across single agents, handoffs, 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.

The recipe is intentionally thin. send_usdc is a plain function decorated with @function_tool; you add it to an Agent's tools list and the Runner picks it up. No special configuration, no extra wrapper, no fork of the SDK. When the Agents SDK ships a new feature (multi-modal inputs, voice agents), your function keeps working because it rides on the standard tool-calling surface - nothing version-specific lives in it.

INSTALLATION

Install the Agents SDK and the core SDK. Two keys.

There is no blockchain0x Agents SDK package to add. You install the OpenAI Agents SDK (the openai-agents package, Python 3.10+) and the real blockchain0x core SDK, then write the function below. That is the whole dependency list.

INSTALL
pip install openai-agents blockchain0x
ENVIRONMENT VARIABLES
export OPENAI_API_KEY=sk-...
export BLOCKCHAIN0X_API_KEY=sk_test_...   # sk_test_ = Base Sepolia, sk_live_ = Base mainnet

OPENAI_API_KEY is your existing OpenAI key (the Agents SDK uses it for the underlying Responses API). BLOCKCHAIN0X_API_KEY is a sk_test_ testnet or sk_live_ mainnet key from your dashboard; the client reads it from the environment. If your agent also receives money, the webhook handler additionally needs BLOCKCHAIN0X_WEBHOOK_SECRET.

THE RECIPE

A @function_tool that pays, handed to an Agent.

Below is the whole integration. send_usdc calls the real blockchain0x client; @function_tool turns it into a tool, and the Runner orchestrates the call. The SDK reads the type hints and docstring to build the schema, so keep them honest. Run it and the agent moves USDC on Base.

AGENT.PY
from agents import Agent, Runner, function_tool
from blockchain0x import Client

blockchain0x = Client()  # reads BLOCKCHAIN0X_API_KEY from the environment

@function_tool
def send_usdc(agent_id: str, to: str, amount_wei: str) -> str:
    """Send a USDC payment from an agent wallet.

    amount_wei is USDC base units (6 decimals), so "10000" is 0.01 USDC.
    """
    return str(
        blockchain0x.payments.create(body={"agentId": agent_id, "to": to, "amountWei": amount_wei})
    )

agent = Agent(
    name="treasurer",
    instructions="You pay vendor invoices in USDC within owner-set limits.",
    tools=[send_usdc],
    model="gpt-4o",
)

result = await Runner.run(
    agent,
    input="Pay 0.01 USDC from agent agt_123 to 0xVendor for the dataset.",
)
print(result.final_output)

When the agent decides to pay, it calls send_usdc, the SDK submits the transfer, and you get a transaction hash back. amount_wei is base units, so 0.01 USDC is "10000". A sk_test_ key keeps it on Base Sepolia until you switch to sk_live_. Add more functions - read a wallet, settle an invoice - the same way; each is another @function_tool in the list.

WEBHOOK HANDLING

Confirm inbound payments with a signed webhook.

If your agent also receives USDC, confirm it with the webhook rather than polling. The verify helper ships in the Node SDK; in a Python service you verify by hand against the documented HMAC, which is all the helper does. FastAPI example below; the same code works in any async Python framework.

WEBHOOK.PY
import hmac, hashlib, os, time
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
SECRET = os.environ["BLOCKCHAIN0X_WEBHOOK_SECRET"].encode()

@app.post("/webhooks/payment")
async def receive(request: Request):
    raw = await request.body()  # RAW bytes - do not parse first
    sig = request.headers.get("X-Blockchain0x-Signature", "")
    ts = request.headers.get("X-Blockchain0x-Timestamp", "")
    parts = dict(p.split("=", 1) for p in sig.split(",") if "=" in p)
    t, v1 = parts.get("t", ts), parts.get("v1", sig)
    want = hmac.new(SECRET, t.encode() + b"." + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(want, v1) or abs(time.time() - int(t)) > 300:
        raise HTTPException(status_code=401)
    if request.headers.get("X-Blockchain0x-Event-Type") == "payment.received":
        await trigger_followup()  # USDC landed - run the next step
    return {"ok": True}

The algorithm is HMAC-SHA256 over the string t.rawBody, a constant-time compare, and a 300-second replay window. Read the raw body via await request.body(), never request.json() re-serialized, because that changes the bytes the signature covers. The shipped events are payment.received, payment.sent, wallet.deployed, and webhook.test. For heavy follow-up work, enqueue a job (Celery, arq) and respond 200 immediately rather than blocking the handler.

SOURCE AND DOCS

The client you are wrapping is open. Read it.

There is no Agents SDK starter package to clone - the recipe above is the integration. The blockchain0x SDKs are open source on GitHub; this recipe wraps the Python SDK (blockchain0x-python), with the full method surface in the docs. Read it for a reference for the function bodies.

github.com/tosh-labs/blockchain0x-python

The full SDK method surface and scopes are documented at the docs. Start on a sk_test_ key against Base Sepolia, then switch to sk_live_ when the function does what you expect.

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

There is no Agents SDK package - you wrap the SDK

Blockchain0x ships adapters for LangChain and CrewAI plus the MCP server; there is no dedicated OpenAI Agents SDK package. The recipe above is the path: decorate a plain typed function with @function_tool, call the real blockchain0x client inside, and add it to Agent(tools=[...]). The SDK reads the signature and docstring to build the tool schema, so keep the docstring accurate.

PITFALL 2

Agents SDK is not the Assistants API

The OpenAI Agents SDK (the openai-agents package, imported as agents) is a different product from the older Assistants API. The recipe targets the Agents SDK: Agent + Runner + @function_tool over the Responses API. If you are calling client.beta.assistants.create(...), you are on the older threads/runs model OpenAI is winding down - move to the Agents SDK and the function above drops straight in.

PITFALL 3

Amounts are USDC base units, as strings

payments.create takes amountWei: a string of USDC base units, not a float. USDC has 6 decimals, so 0.01 USDC is "10000" and 5 USDC is "5000000". Type the function argument as str; a float will lose precision before it reaches the API. Keep it a string end to end.

PITFALL 4

send_payment can answer 503 early on

payments.create does not retry by default and can return 503 until the chain adapter is wired for your network. Catch the error inside your function and return a clear message the model can act on, rather than letting the Runner loop. The auto-minted idempotency key means a manual retry will not double-pay.

PITFALL 5

Async-only runtime

The Agents SDK is async-first - await Runner.run(...). The blockchain0x call inside your tool is synchronous, which is fine for a single quick payment but blocks the loop under load. If you are running many concurrent agents, wrap the SDK call with asyncio.to_thread. From a sync entry point, asyncio.run() at the top level.

FREQUENTLY ASKED

Three OpenAI Agents SDK questions.

Is there a dedicated OpenAI Agents SDK package to install?

No. The Agents SDK already turns a decorated function into a tool with @function_tool, so the honest path is to wrap the real blockchain0x client yourself, as shown above. The only shipped framework packages are blockchain0x-langchain and blockchain0x-crewai (both Python) plus the @blockchain0x/mcp server. The Agents SDK, like the other frameworks without a dedicated adapter, is this few-line recipe.

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

Yes. The Responses API is the tool-calling layer the Agents SDK builds on. If you call client.responses.create() directly, declare the same function as a tool in the request's tools list and dispatch the call yourself when the model asks for it - the body is just the blockchain0x.payments.create call from the recipe. The Agents SDK is the path of least resistance because @function_tool builds that tool schema and dispatch for you.

Does this work with multi-agent handoffs?

Yes, and you decide which agent owns the wallet. The clean pattern is to give the payment function to a single front-facing agent and have it hand off the actual work to specialist agents that carry no wallet tools. Spending authority stays in one place, so there is no wrong-agent charging. Add read and settle functions the same way - blockchain0x.transactions.get, blockchain0x.agents.get, blockchain0x.payment_requests.settle - each as its own @function_tool.

Add payments to your Agents SDK build.

A few lines wrapping the real client, no package to install. Free to start.