DEV Community: Dutiful

How an agent finds a paid endpoint: .well-known/x402.json, llms.txt and an MCP server card

Dutiful — Sat, 24 Oct 2026 06:16:02 +0000

Disclosure: I build Dutiful, the service used as the example. The files below are Dutiful's own published discovery artifacts - treat them as our setup, not a specification or a guarantee that any framework supports them.

A previous post (https://dev.to/dutiful_dev/how-an-agent-pays-for-and-reads-a-company-check-over-x402-3dh3) walked through paying for an HTTP request with x402: create the order, read the 402, sign, retry. It assumed the agent already knew where to knock. Before any payment can happen, an agent has to find the endpoint and learn what to POST. A landing page written for humans leaves an agent guessing at routes and body shapes. These are the files I publish so it does not have to guess.

/.well-known/x402.json: the payment facts, machine-readable

This is the x402 discovery document. Schematic excerpt, trimmed for length - the live file is at https://dutiful.work/.well-known/x402.json:

{"version": 2, "resources": [{
  "resource": "https://dutiful.work/api/order/{order}/entity",
  "accepts": [{ "scheme": "exact", "network": "eip155:8453",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "3000000", "payTo": "0x1CD7...fA52", "maxTimeoutSeconds": 1800 }],
  "extensions": { "bazaar": { "info": { "input": ..., "output": ... }, "schema": ... } }
}]}

Without creating an order or paying anything, an agent reading this file learns the resource URL, the scheme, the network (eip155:8453 is Base), the asset (USDC), the amount (3000000 units, $3.00), the payee, and the maxTimeoutSeconds value (1800) that the payment requirements will carry. The bazaar extension goes further: a JSON schema and an example for the input body and the output, so a crawler or planner can learn the request shape from the file itself.

/openapi.json: the whole contract, payment terms included

Standard OpenAPI 3, with one extension: x-payment-info declares the protocol (x402), network, asset, amount and payee in the same document that lists the routes. An agent that consumes OpenAPI learns the free POST /api/order coverage check, the entity step that returns 402, the pay route - and /api/pay-demo, a metadata-only route that answers 402 so directory crawlers can index the payment shape but never accepts a payment.

/llms.txt: a short plain-text summary

llms.txt is a compact text file written for language-model readers: what the products are, which pages matter, and the exact machine-use flow in five lines:

Company Report API: POST /api/order {company,country} -> JSON candidates;
POST /api/order/{order}/entity {idx} -> 402 x402 requirements;
POST /api/order/{order}/pay with PAYMENT-SIGNATURE header;
GET /api/order/{order} -> status + report.
Discovery: /.well-known/x402.json, /openapi.json.

Whether a given agent's framework picks it up depends on that framework - but the file costs nothing to publish, and when it is read, five exact flow lines beat a page of marketing.

/.well-known/mcp/server-card.json: the MCP route

Agents that speak MCP get a different front door. The server card describes a streamable-HTTP MCP server with three tools - check_coverage (free), create_order and get_report - each with a full input schema. One honest detail: the MCP tools do not handle the payment itself. create_order says plainly that it "does not pay" - paying still means sending the signed payment in a PAYMENT-SIGNATURE header to the returned pay_url, then reading the result with get_report. MCP covers discovery, ordering and delivery; the signature step stays a raw HTTP call.

What I would tell someone building a paid agent endpoint

Put a free step first. check_coverage costs nothing, so agents can explore and fail cheap. Payment is only requested after the free coverage check has run and an entity is chosen.
Make every layer self-describing. The 402 response itself carries the amount, payee, network and timeout values the client needs to sign.
Give crawlers a demo 402. A metadata-only pay route lets directories index the payment shape without touching a real order.
Publish two front doors. Raw HTTP with OpenAPI and x402.json for general agents; an MCP card for MCP clients. Same service underneath.
Write llms.txt for the agent, not the human. Exact flow lines, not vision statements.

Honest close

None of this creates distribution on its own. The directory ecosystem for x402 services is young, our directory submissions are mostly still pending or unavailable, and reach today is small - these files simply make the service legible to whatever does come looking. If an agent finds the endpoint through one of them, that is the point.

Feedback welcome: what else would your agent need to discover before it trusts a paid endpoint? Docs and links: https://dutiful.work/developers . Sample report: https://dutiful.work/sample . Contact: dutifulhq@proton.me.

How an agent pays for and reads a company check over x402

Dutiful — Fri, 23 Oct 2026 19:31:56 +0000

Disclosure: I build Dutiful, the service used in this example.

Agents are good at calling APIs and bad at filling in sign-up forms. x402 is a way to pay for an HTTP request in the request itself: the server answers 402 Payment Required with the terms, the client signs a payment, and retries. No account, no API key, no billing page. This post walks through that flow with a real endpoint, a company background check.

What the service returns

Give it a company name and a country. It checks coverage for free, then, once paid ($3.00 USDC per report), returns a report: registry profile, officers and owners where the register publishes them, a sanctions screen (OFAC SDN and UK Sanctions List) and a news and web scan. Each finding names its source, and the report lists what it could not check. It covers 12 countries across Europe, Israel and North America, partially in the US and Canada.

The flow

Create an order (free coverage check): POST https://dutiful.work/api/order {"company":"Tesco PLC","country":"GB"} The response lists candidate entities, so the agent can pick the right one.
Select the entity: POST /api/order/{order}/entity {"idx":0} This answers 402 with the x402 payment requirements: amount, payee and network (USDC on Base).
Pay: sign the requirements with the agent's wallet and send the signature in the PAYMENT-SIGNATURE header: POST /api/order/{order}/pay
Read the result: GET /api/order/{order} -> status, report, report_text

Coverage is checked and the entity chosen before any payment is requested.

Signing the payment

Step 3 is where the client does the work: it reads the 402 body, builds the authorization for your wallet, and retries with the header. A minimal working client (Node 18+, viem), tested against the x402 facilitator on testnet:

// Minimal x402 client for Dutiful: check a company, pay in USDC on Base, read the report.
// Needs Node 18+ and `npm i viem`. Set PRIVATE_KEY to a wallet holding USDC on Base.
// Usage: PRIVATE_KEY=0x... node dutiful-x402-client.mjs "Tesco PLC" GB
import { privateKeyToAccount } from "viem/accounts";
import { randomBytes } from "node:crypto";

const BASE = process.env.DUTIFUL_URL || "https://dutiful.work";
const J = { "content-type": "application/json" };

export async function buyReport(company, country, { privateKey, baseUrl = BASE, fetchImpl = fetch, pickIdx = 0 } = {}) {
  const account = privateKeyToAccount(privateKey);
  const call = async (path, body, headers = {}) => {
    const r = await fetchImpl(baseUrl + path, { method: "POST", headers: { ...J, ...headers }, body: JSON.stringify(body || {}) });
    return { status: r.status, json: await r.json().catch(() => ({})) };
  };

  // 1. Free coverage check: candidate entities, no payment.
  const order = await call("/api/order", { company, country, ref: "devto-report" });
  if (order.status !== 200 || !order.json.candidates?.length) throw new Error("no coverage: " + JSON.stringify(order.json));
  const id = order.json.order;

  // 2. Pick the entity: the server answers 402 with the x402 payment requirements.
  const quote = await call(`/api/order/${id}/entity`, { idx: pickIdx });
  if (quote.status !== 402) throw new Error("expected 402, got " + quote.status);
  const req = quote.json.accepts[0]; // { scheme:"exact", network, asset, amount, payTo, extra:{name,version} }

  // 3. Sign an EIP-3009 transferWithAuthorization for exactly that amount (gasless for the payer).
  const chainId = Number(req.network.split(":")[1]);
  const auth = {
    from: account.address, to: req.payTo, value: BigInt(req.amount),
    validAfter: 0n, validBefore: BigInt(Math.floor(Date.now() / 1000) + req.maxTimeoutSeconds),
    nonce: "0x" + randomBytes(32).toString("hex"),
  };
  const signature = await account.signTypedData({
    domain: { name: req.extra.name, version: req.extra.version, chainId, verifyingContract: req.asset },
    types: { TransferWithAuthorization: [
      { name: "from", type: "address" }, { name: "to", type: "address" }, { name: "value", type: "uint256" },
      { name: "validAfter", type: "uint256" }, { name: "validBefore", type: "uint256" }, { name: "nonce", type: "bytes32" } ] },
    primaryType: "TransferWithAuthorization", message: auth,
  });
  const payload = { x402Version: 2, accepted: req, payload: { signature, authorization: Object.fromEntries(Object.entries(auth).map(([k, v]) => [k, typeof v === "bigint" ? v.toString() : v])) } };
  const header = Buffer.from(JSON.stringify(payload)).toString("base64");

  // 4. Submit payment, then poll for the report.
  const paid = await call(`/api/order/${id}/pay`, {}, { "PAYMENT-SIGNATURE": header });
  if (paid.status !== 200) throw new Error("payment rejected: " + JSON.stringify(paid.json));
  for (let i = 0; i < 60; i++) {
    const s = await (await fetchImpl(`${baseUrl}/api/order/${id}`)).json();
    if (s.status === "delivered") return s;
    await new Promise(r => setTimeout(r, 5000));
  }
  throw new Error("not delivered yet; keep order id " + id + " and poll GET /api/order/" + id);
}

if (import.meta.url === `file://${process.argv[1]}`) {
  const [company, country] = process.argv.slice(2);
  const r = await buyReport(company, country, { privateKey: process.env.PRIVATE_KEY });
  console.log(r.report_text || JSON.stringify(r, null, 2));
}

Needs a wallet holding USDC on Base. The authorization is gasless for the payer.

As a tool in an agent

There is also an MCP server with three tools: check_coverage (free), create_order (returns the payment requirements) and get_report. Docs, openapi.json and .well-known/x402.json are linked from https://dutiful.work/developers .

What to know

Sales are final. Your report stays on its private link for at least a week after delivery - download the PDF to keep a copy. The report is research from public sources, not a compliance certificate. Sample report: https://dutiful.work/sample . Questions or problems: dutifulhq@proton.me.

I would like feedback on the two-step flow and on what else an agent needs before it trusts a payment endpoint.