Meterlane x402 USDC Payments with OpenAI Agents SDK

The OpenAI Agents SDK lets you give an agent a set of callable tools with typed parameters. By wrapping createAgentClient from @meterlane/x402/client inside a tool() definition, your agent can reach any Meterlane x402-gated route without you writing any payment-retry logic — the client handles the 402 → sign → retry cycle transparently inside the tool’s execute function.

All examples on this page target Base Sepolia (eip155:84532) and the public sandbox demo route. Do not use mainnet keys or mainnet facilitators in development or CI.

Install dependencies

You need @openai/agents for the agent runtime, zod for parameter schemas, and @meterlane/x402 for the x402 payment client.

npm add @openai/agents zod @meterlane/x402

Import the MIT-licensed client — not the server middleware:

import { createAgentClient } from "@meterlane/x402/client";

The client is MIT-licensed; audit what it signs before running it with a funded wallet.

Set your environment variable

Never embed your private key in source code or commit it to version control. Store it in AGENT_PRIVATE_KEY and load it at runtime. Use a dedicated hot wallet with a limited USDC balance — do not reuse cold-storage or exchange keys.

AGENT_PRIVATE_KEY=0xYOUR_BASE_SEPOLIA_PRIVATE_KEY
OPENAI_API_KEY=sk-...

Get test USDC for Base Sepolia from the Circle faucet — select Base Sepolia before requesting.

Create the payment tool

The tool calls paidFetch — a fetch wrapper that handles x402 automatically — instead of calling fetch directly.

import { Agent, run, tool } from "@openai/agents";
import { z } from "zod";
import type { Hex } from "viem";
import { createAgentClient } from "@meterlane/x402/client";

const privateKey = process.env.AGENT_PRIVATE_KEY as Hex | undefined;
if (!privateKey?.startsWith("0x")) {
  throw new Error("Set AGENT_PRIVATE_KEY to a 0x-prefixed Base Sepolia funded key");
}

// Returns a fetch wrapper that pays 402 automatically
const paidFetch = createAgentClient(privateKey, "eip155:84532");

const gatewayBase =
  process.env.GATEWAY_URL ?? "https://gateway.meterlane.app";
const orgSlug = process.env.ORG_SLUG ?? "demo";

const meterlanePaidGet = tool({
  name: "meterlane_paid_get",
  description:
    "HTTP GET to a Meterlane x402 gateway route. Pays with USDC on Base Sepolia when the server returns 402.",
  parameters: z.object({
    path: z
      .string()
      .describe("Route path under /gateway/:orgSlug, e.g. /demo"),
  }),
  execute: async ({ path }) => {
    const normalized = path.startsWith("/") ? path : `/${path}`;
    const url = `${gatewayBase}/gateway/${orgSlug}${normalized}`;

    const res = await paidFetch(url, { method: "GET" });
    const text = await res.text();

    return {
      ok: res.ok,
      status: res.status,
      bodyPreview: text.slice(0, 500),
    };
  },
});

Attach the tool to an agent and run it

Pass the tool to an Agent instance, then call run() with a prompt:

const agent = new Agent({
  name: "Meterlane payer",
  instructions:
    "You can call meterlane_paid_get to access paid Meterlane API routes. Use path /demo when asked to test connectivity.",
  tools: [meterlanePaidGet],
});

async function main() {
  if (!process.env.OPENAI_API_KEY) {
    // Smoke test the payment flow without spending model tokens
    const direct = await meterlanePaidGet.invoke({ path: "/demo" });
    console.log("Direct tool result:", direct);
    return;
  }

  const result = await run(
    agent,
    "Call meterlane_paid_get with path /demo and report the HTTP status code.",
  );
  console.log(result.finalOutput);
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

Run the file:

AGENT_PRIVATE_KEY=0xYOUR_KEY npx tsx openai-agents-meterlane.ts

Without OPENAI_API_KEY the script invokes the tool directly, which is useful for verifying that your wallet is funded and the payment flow works before you spend model tokens.

The tool, invoke, and run APIs vary slightly across @openai/agents versions. Adjust imports to match your installed version — the payment logic inside execute stays unchanged regardless.

How it works

When the agent calls meterlanePaidGet, the execute function fires paidFetch(url). The x402 cycle runs inside that call:

The client sends a plain GET to the gateway.
The gateway returns 402 with an X-Payment-Requirements header describing the USDC price and receiver address.
ExactEvmScheme uses your private key to sign an ERC-3009 authorization for that amount on Base Sepolia.
The client retries the request with the authorization attached as a payment header.
The gateway settles on-chain and returns 200 with the upstream response body.
The tool returns { ok: true, status: 200, bodyPreview } to the agent.

Use "eip155:84532" (Base Sepolia) with the default public x402.org facilitator for all development work. Production deployments that need Base mainnet require a private mainnet-capable facilitator configured in your Meterlane dashboard under Settings → Developer.

​How it works

How it works