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.
Any language. Write the request in any language or script. Set preferred_output_language (e.g. ru, ja, pt-BR) for explanations; otherwise the detected request language is used, with an English fallback reported in language.note for ambiguous mixed input. Geography is independent of language: local markets are searched in their own languages (search_plan). Vendor names, quotes, addresses and prices stay verbatim in the original; quote_translation and name_alias are convenience only.
Spending ceiling. Add max_price_usdc to refuse with 422 price_exceeds_ceiling before any payment if the tier price is higher.
2. Review the price and pay
Quick: 0.27 USDC. Standard: 0.46 USDC. Deep: 0.58 USDC.
The price is fixed before payment: the measured variable cost of one research attempt for the tier (search, model, compute, database, settlement), multiplied by the configured markup. Actual usage is recorded per request; there is no usage surcharge or automatic price true-up. Current cost multiplier: 3; minimum: 0.10 USDC. Check the quote before signing.
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) <= 460000n
));
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
Example request JSON ↗ · Complete response example (fictional demo) ↗
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 requirement_checks (verified with a quote, inferred, or unknown; mandatory ones must be verified), match_reasons, requirements_met, requirements_unverified, vendor_type, location, service_area, availability, nullable pricing and contact fields, confidence with its basis, evidence URLs with verbatim quotes, source_language 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
| Status | Meaning | Action |
|---|---|---|
| 400 / 413 / 415 | Invalid or oversized input | Correct input; nothing charged. |
| 401 / 404 | Missing access key / inaccessible result | Use the original secret key. |
| 402 | Payment required or invalid | Read the current challenge; apply a spending limit. |
| 409 | Key or payment already used | Retrieve the original request. |
| 429 | Rate limit | Wait for Retry-After. |
| 503, paid: true | Research failure | Retry the same body and key, up to twice, without a new payment. |
| 503, settlement_unknown | Uncertain settlement | Do not sign again. Preserve request ID for reconciliation. |
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.