OpenAI function calling

agent402-openai-tools · npm · MIT

Turns Agent402 tools into OpenAI function-calling definitions. The returned tools array is the same JSON used by chat.completions and the Responses API, and execute runs whatever tool call the model returns.

Install

npm install openai agent402-openai-tools @x402/fetch @x402/core @x402/evm viem

Example

import OpenAI from "openai";
import { agent402Tools } from "agent402-openai-tools";
import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const payClient = new x402Client();
registerExactEvmScheme(payClient, { signer: privateKeyToAccount(process.env.AGENT_KEY) });
const payFetch = wrapFetchWithPayment(fetch, payClient);

const openai = new OpenAI();
// web search, then a cited answer: both paid per call from the wallet
const { tools, execute } = await agent402Tools({ slugs: ["search", "answer"], freeOnly: false, fetch: payFetch });

const messages = [{ role: "user", content: "Search the web for x402 payment protocol adoption, then answer with citations: what is the x402 payment protocol?" }];
for (let turn = 0; turn < 4; turn++) {
  const res = await openai.chat.completions.create({ model: "gpt-4o-mini", messages, tools });
  const msg = res.choices[0].message;
  messages.push(msg);
  if (!msg.tool_calls?.length) { console.log(msg.content); break; }
  for (const call of msg.tool_calls) {
    const result = await execute(call.function.name, JSON.parse(call.function.arguments));
    messages.push({ role: "tool", tool_call_id: call.id, content: JSON.stringify(result) });
  }
}

No wallet yet? The pure-CPU tools (hash, uuid, base64, markdown, JSON and more) run free with proof-of-work and no wallet:

// free tier: every tool listed here is compute-payable (proof-of-work, no wallet)
const { tools, execute } = await agent402Tools({ slugs: ["hash", "markdown-to-html", "text-stats", "uuid"] });

What it exposes

One native tool per catalog slug you pass in slugs (a short list gives the model better tool selection).
With no slugs, the free-tier catalog: every compute-payable tool (freeOnly: true is the default).
An execute(name, args) function that runs a tool call and pays for it underneath.
baseUrl points the adapter at a self-hosted Agent402 instance.

How payment works

Free tier: compute-payable tools settle with a sha256 proof-of-work solved in-process. No wallet, no API key.
Wallet-only tools (browser, network, memory, live data): set freeOnly: false and pass a payment-wrapped fetch. An @x402/fetch fetch pays in USDC over x402; a stock mppx fetch pays over MPP. The same 402 carries both offers.
Prices come from the live catalog at /api/pricing and are quoted in every 402 before anything is signed.

A paid call that ends in any status of 400 or above is not charged over x402: settlement runs after the tool and only on a successful response. Background: What x402 is · MPP (Machine Payments Protocol).

Configuration

Option	Type	Description
`slugs`	`string[]`	Load only these tools (a short list gives the model better tool selection).
`freeOnly`	`boolean`	Default true: keep only compute-payable tools, paid with proof-of-work. Set false to include wallet-only tools.
`fetch`	`typeof fetch`	A payment-wrapped fetch (@x402/fetch for x402, mppx for MPP) that pays wallet-only tools.
`baseUrl`	`string`	Point to a self-hosted Agent402 instance.

// Load only these tools (a short list gives the model better tool selection).
agent402Tools({ slugs: ["hash", "markdown-to-html"] })

// Default true: keep only compute-payable tools, paid with proof-of-work. Set false to include wallet-only tools.
agent402Tools({ slugs: ["extract", "hash"], freeOnly: false, fetch: payFetch })

// A payment-wrapped fetch (@x402/fetch for x402, mppx for MPP) that pays wallet-only tools.
agent402Tools({ freeOnly: false, fetch: payFetch })

// Point to a self-hosted Agent402 instance.
agent402Tools({ baseUrl: "https://my-agent402.example.com" })

works withOpenAI chat.completionsOpenAI Responses API