# 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
- A wallet on Base mainnet holding a little USDC. One `dns-lookup` call costs $0.003; quick tools cost $0.003 to $0.02 per call, so $0.10 of USDC covers 33 `dns-lookup` calls. Payments are x402 `exact` USDC 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).

## 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.
```js
// 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.
```js
// 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)
- **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.status` says why: `used_up_today` (3 free calls used; resets 00:00 UTC), `daily_cap_reached` (the shop's daily trial cap) or `not_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-After` seconds, then retry once.
- **409** `payment_in_use`: the same signed payment was sent twice at once. Make a new call.

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

## 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/post`
- `page-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.com`
- `site-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.com`
- `email-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.com`
- `pdf-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://docs.x402.org/getting-started/quickstart-for-buyers (@x402/fetch, @x402/core, @x402/evm 2.x)
- https://registry.npmjs.org/x402-fetch (x402-fetch 1.2.0, deprecated v1)
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.
