← All guides · Markdown: /guides/x402-fetch.md

Node: @x402/fetch (x402 v2) and x402-fetch (v1)

Pay per call from Node with the official x402 fetch wrapper: the first request gets the 402, the wrapper signs a USDC payment and retries.

For: Node.js 20+. 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

Prerequisites

Pay per call: @x402/fetch (x402 v2, recommended)

Save as lordevo.mjs. The helper also does the free trial, and is reused by the LangChain, OpenAI Agents and Vercel AI SDK guides.

// npm i @x402/fetch @x402/core @x402/evm viem
import { wrapFetchWithPayment } from '@x402/fetch';
import { x402Client } from '@x402/core/client';
import { ExactEvmScheme } from '@x402/evm/exact/client';
import { privateKeyToAccount } from 'viem/accounts';

const BASE = "https://shop.lordevo.com";
// Pays x402 402s in USDC on Base mainnet. Without AGENT_WALLET_KEY only free trial calls work.
let payFetch = null;
if (process.env.AGENT_WALLET_KEY) {
  const client = new x402Client();
  client.register('eip155:8453', new ExactEvmScheme(privateKeyToAccount(process.env.AGENT_WALLET_KEY)));
  payFetch = wrapFetchWithPayment(fetch, client);
}
let noTrialUntil = 0; // after "used_up_today", skip the free attempt until 00:00 UTC

// One Lordevo call. trial: true asks for a free call first (no payment) and pays only when no free call is left.
// Errors throw with .status, .body and .retryAfter; refused or failed calls are not charged.
export async function lordevo(tool, params = {}, { trial = false } = {}) {
  const query = Object.fromEntries(Object.entries(params).filter(([, v]) => v != null && v !== ''));
  const url = `${BASE}/api/quick/${tool}?${new URLSearchParams(query)}`;
  if (trial && Date.now() >= noTrialUntil) {
    const r = await fetch(url, { headers: { accept: 'application/json', 'x-lordevo-trial': '1' } });
    if (r.status !== 402) return answer(r);
    const why = (await r.json().catch(() => null))?.free_trial?.status;
    if (why === 'used_up_today' || why === 'daily_cap_reached') noTrialUntil = (Math.floor(Date.now() / 864e5) + 1) * 864e5;
    if (!payFetch) throw Object.assign(new Error(`No free call left (${why || 'not_eligible'}); set AGENT_WALLET_KEY to pay per call.`), { status: 402, body: null, retryAfter: null });
  }
  if (!payFetch) throw Object.assign(new Error('Set AGENT_WALLET_KEY to pay per call, or pass { trial: true }.'), { status: 402, body: null, retryAfter: null });
  return answer(await payFetch(url, { headers: { accept: 'application/json' } }));
}

async function answer(r) {
  const body = await r.json().catch(() => null);
  if (r.ok) return body;
  throw Object.assign(new Error(body?.message || body?.error || `HTTP ${r.status}`), { status: r.status, body, retryAfter: Number(r.headers.get('retry-after')) || null });
}

// For agent tools: the model gets errors as JSON it can read, instead of an exception.
export async function lordevoTool(tool, params) {
  try { return JSON.stringify(await lordevo(tool, params, { trial: true })); }
  catch (e) { return JSON.stringify({ error: e.body?.error || (e.status ? `http_${e.status}` : 'network_error'), message: e.message, retry_after_seconds: e.retryAfter ?? null, ...(e.status ? { charged: false } : {}) }); }
}

// Try it: node lordevo.mjs
console.log(await lordevo("dns-lookup", {"host":"example.com"}, { trial: true }));

Try it free (no wallet)

Leave AGENT_WALLET_KEY unset and pass { trial: true }: the helper sends X-Lordevo-Trial: 1 and no payment. 3 free calls per IP per UTC day on tools up to $0.005; the answer carries _trial.free_calls_left_today. With the key set, { trial: true } uses the free calls first and then pays.

x402 v1: x402-fetch

The v1 package still works here (the shop accepts v1 X-PAYMENT too), but it is deprecated upstream; prefer @x402/fetch for new code.

// npm i x402-fetch viem
import { wrapFetchWithPayment } from 'x402-fetch';
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { base } from 'viem/chains';

const wallet = createWalletClient({ account: privateKeyToAccount(process.env.AGENT_WALLET_KEY), chain: base, transport: http() });
// maxValue in USDC base units: 20000 = $0.02, the dearest quick tool; anything above is refused.
const payFetch = wrapFetchWithPayment(fetch, wallet, BigInt(20000));
const r = await payFetch("https://shop.lordevo.com/api/quick/dns-lookup?host=example.com", { headers: { accept: 'application/json' } });
console.log(r.status, await r.json());

Errors (nothing is charged on any of these)

The helper throws an Error with .status, .body and .retryAfter; lordevoTool() returns the same as JSON for agent tools.

Next tools to try

Checked

Written 2026-10-30 against the current public docs:

The @x402/fetch helper was run end to end on 2026-10-30 against a local copy of this shop (@x402/fetch 2.28.0, test network, test facilitator that checks the signature): free trial call, then a signed payment. On 2026-11-09 both snippets were run again against a local copy of this shop (@x402/fetch 2.29.0 and x402-fetch 1.2.0, test network Base Sepolia, test facilitator; only the base URL, network and chain changed): the free trial call, a paid @x402/fetch call and a paid x402-fetch v1 call all answered 200.