A need in.
A shortlist out.

1. Describe your need

Send JSON or plain text. Create a random, secret Idempotency-Key of 16–128 letters, digits, underscores or hyphens. Keep it for all retries and result retrieval.

curl -i https://vendorfinder.online/api/v1/find   -H 'Content-Type: application/json'   -H 'Idempotency-Key: REPLACE_WITH_RANDOM_UUID'   -d '{"need":"API for extracting tables from PDF files",
       "must_have":["REST API","Commercial use permitted"],
       "tier":"standard","max_results":5}'

Optional fields include category, requirements, location, service_area, budget, quantity, deadline, nice_to_have and exclude. Location means vendor location; service_area means where a vendor must deliver or operate. Dates use YYYY-MM-DD. See the OpenAPI schema for exact types and limits.

2. Review the price and pay

The first request returns 402 with x402 v2 payment requirements in the JSON body and base64-encoded PAYMENT-REQUIRED header. A free POST /api/v1/quote also returns the current price for your input. Sign a USDC EIP-3009 authorization using an x402-compatible client and retry the identical body and key with PAYMENT-SIGNATURE.

import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";

// signer is YOUR agent's wallet signer, never the seller's key.
const client = new x402Client();
registerExactEvmScheme(client, { signer });
// Add your spending policy before allowing automatic payment.
client.registerPolicy((_version, options) => options.filter(
  p => p.network === "eip155:8453" && BigInt(p.amount) <= 750000n
));
const paidFetch = wrapFetchWithPayment(fetch, client);
const key = crypto.randomUUID(); // persist before submitting
const response = await paidFetch(
  "https://vendorfinder.online/api/v1/find", {
    method: "POST",
    headers: { "Content-Type": "application/json",
               "Idempotency-Key": key },
    body: JSON.stringify({need: "API for extracting tables from PDF files"})
  }
);
const result = await response.json();

Settlement is confirmed before research begins. On success, PAYMENT-RESPONSE contains the receipt. The seller only configures a receiving public address; the seller’s private key is never part of this service.

3. Consume or retrieve the result

A completed request returns 200 and a Vendor Shortlist. Research runs within the request, normally under three minutes. Concurrent retries may receive 202 with the existing request ID. Retrieve it with the original key:

GET /api/v1/requests/{request_id}
Authorization: Bearer <original Idempotency-Key>

Each vendor contains match_reasons, requirements_met, requirements_unverified, inferred_information, nullable pricing and contact fields, evidence URLs with verbatim quotes, and retrieval timestamps. No-match results are completed research and are charged. Source claims are not a guarantee of current stock or suitability.

Errors & retries

If the connection is interrupted, retry the exact request with the same key. Never create a new key just because you did not receive a response. Result access is private to holders of this key. Don’t share it in public URLs.

Demo and live mode

Demo responses identify themselves as mode: demo, contain fictional PDF API vendors, and never accept real payments. For a local demo, send PAYMENT-SIGNATURE: demo:<Idempotency-Key>. Live mode rejects this header and requires durable storage plus configured providers.

Privacy

Requests and results are stored for retrieval. Live request text is sent to search and model providers; payment authorization goes to CDP. Don’t submit confidential designs, personal information or secrets. Application logs omit request text, credentials and payment signatures. This MVP does not contact vendors on your behalf.