← All guides · Markdown: /guides/openai-agents.md
OpenAI Agents SDK: a function tool that pays per call
Wrap one paid call as a function tool for the OpenAI Agents SDK, in JavaScript or Python, free trial first.
For: Agents SDK (JS and Python). Endpoint shape: GET https://shop.lordevo.com/api/quick/<tool>?<input> (HTTP 402 with x402 terms until paid). All guides: https://shop.lordevo.com/guides
Easier: use the SDK: https://shop.lordevo.com/guides/sdk/openai-agents-js (JavaScript) or https://shop.lordevo.com/guides/sdk/openai-agents-python (Python)
Prerequisites
- A wallet on Base mainnet holding a little USDC. One
dns-lookupcall costs $0.003; quick tools cost $0.003 to $0.02 per call, so $0.10 of USDC covers 33dns-lookupcalls. Payments are x402exactUSDC transfers that your wallet signs; the facilitator submits them, so the wallet needs no ETH for gas. - The wallet's private key in the environment variable
AGENT_WALLET_KEY, never in code. Use a separate agent wallet with a small balance: an x402 client pays the amount the 402 asks for (the shop's prices are fixed per tool, listed in https://shop.lordevo.com/catalog.json). - No account, sign-up or API key. Instant tools that fail or are refused are not charged. Long jobs (202) are charged when accepted and are not refunded automatically if they fail later. If a paid job failed, email hello@lordevo.com with the transaction hash and we'll review it, usually within 2 business days.
- To try without a wallet: 3 free calls per IP per UTC day on the 52 tools priced up to $0.005 (opt-in, see below).
JavaScript (@openai/agents)
Put the helper from https://shop.lordevo.com/guides/x402-fetch in lordevo.mjs next to this file. The SDK expects zod 4.
// npm i @openai/agents zod (plus the helper's packages; OPENAI_API_KEY in the environment)
import { Agent, run, tool } from '@openai/agents';
import { z } from 'zod';
import { lordevoTool } from './lordevo.mjs'; // tries a free trial call first (X-Lordevo-Trial: 1), then pays
const dnsLookup = tool({
name: "dns_lookup",
description: "DNS records lookup (A, AAAA, CNAME, MX, TXT, NS, SOA, CAA). Costs $0.003 per call (x402, USDC on Base); 3 free trial calls per IP per UTC day (shared by all tools up to $0.005). Instant tools that fail or are refused are not charged. Long jobs (202) are charged when accepted and are not refunded automatically if they fail later. If a paid job failed, email hello@lordevo.com with the transaction hash and we'll review it, usually within 2 business days.",
parameters: z.object({
host: z.string().describe("Host name to look up, e.g. example.com or mail.example.com (a URL also works; the host part is used)"),
type: z.enum(["ALL","A","AAAA","CNAME","MX","TXT","NS","SOA","CAA"]).nullable().describe("Record type (default ALL = A, AAAA, CNAME, MX, TXT, NS, SOA, CAA)"),
}),
execute: input => lordevoTool("dns-lookup", input),
});
const agent = new Agent({ name: 'Web analyst', instructions: 'Answer with checked facts.', tools: [dnsLookup] });
const result = await run(agent, "Use the dns_lookup tool on example.com and summarise the answer.");
console.log(result.finalOutput);
Optional fields are .nullable() because the SDK uses strict JSON schemas; the helper drops null values.
Python (openai-agents)
Put the helper from https://shop.lordevo.com/guides/python in lordevo.py next to this file.
# pip install openai-agents (plus the helper's packages; OPENAI_API_KEY in the environment)
from agents import Agent, Runner, function_tool
from lordevo import lordevo_tool # tries a free trial call first (X-Lordevo-Trial: 1), then pays
@function_tool
def dns_lookup(host: str, type: str | None = None) -> str:
"""DNS records lookup (A, AAAA, CNAME, MX, TXT, NS, SOA, CAA). Costs $0.003 per call (x402, USDC on Base); 3 free trial calls per IP per UTC day (shared by all tools up to $0.005). Instant tools that fail or are refused are not charged. Long jobs (202) are charged when accepted and are not refunded automatically if they fail later. If a paid job failed, email hello@lordevo.com with the transaction hash and we'll review it, usually within 2 business days.
Args:
host: Host name to look up, e.g. example.com or mail.example.com (a URL also works; the host part is used)
type: Record type (default ALL = A, AAAA, CNAME, MX, TXT, NS, SOA, CAA) One of ALL, A, AAAA, CNAME, MX, TXT, NS, SOA, CAA.
"""
return lordevo_tool("dns-lookup", {"host": host, "type": type})
agent = Agent(name="Web analyst", instructions="Answer with checked facts.", tools=[dns_lookup])
print(Runner.run_sync(agent, "Use the dns_lookup tool on example.com and summarise the answer.").final_output)
Try it free (no wallet)
Both tools try a free call first (3 per IP per UTC day on tools up to $0.005); without AGENT_WALLET_KEY the agent gets {"error": "http_402", ...} once they are used up.
Errors (nothing is charged on any of these)
- 400 / 422: bad or unusable input (body
{"error", "message", "charged": false}). Fix the input; do not retry as is. - 403: robots.txt does not allow the shop to fetch that URL. Pick another URL.
- 402: payment needed. On a trial request,
free_trial.statussays why:used_up_today(3 free calls used; resets 00:00 UTC),daily_cap_reached(the shop's daily trial cap) ornot_eligible(tool above $0.005). Pay per call instead. With a paying client, a final 402 means the payment was not accepted: check the USDC balance on Base (eip155:8453). - 429 / 503: busy or rate-limited. Wait
Retry-Afterseconds, then retry once. - 409
payment_in_use: the same signed payment was sent twice at once. Make a new call.
The tools never throw: errors reach the model as JSON (error, message, retry_after_seconds, charged: false).
Next tools to try
can-fetch($0.003, free trial ok): Can I fetch this URL? robots.txt + AI-crawler permission gate.GET https://shop.lordevo.com/api/quick/can-fetch?url=https://example.com/blog/postpage-markdown($0.003, free trial ok): URL to Markdown: LLM-ready web page reader (main content).GET https://shop.lordevo.com/api/quick/page-markdown?url=https://example.comsite-check($0.02): Site check: URL risk signals + AI readiness + security headers (recommended start).GET https://shop.lordevo.com/api/quick/site-check?url=https://example.comemail-validate($0.003, free trial ok): Email validation / email verification API (syntax + domain + MX, no SMTP probing).GET https://shop.lordevo.com/api/quick/email-validate?email=jane@example.compdf-text($0.003, free trial ok): PDF to text, page by page.GET https://shop.lordevo.com/api/quick/pdf-text?url=https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf- All 58 tools with prices and inputs: https://shop.lordevo.com/catalog.json, https://shop.lordevo.com/llms.txt, https://shop.lordevo.com/quick
Checked
Written 2026-10-30 against the current public docs:
- https://openai.github.io/openai-agents-js/guides/tools/ (@openai/agents 0.21.0, tool() with zod ^4)
- https://openai.github.io/openai-agents-python/tools/ (openai-agents 0.24.0, @function_tool)
The snippets follow those docs; they were not executed end to end by the shop. Tell us if something has moved: hello@lordevo.com