1. Describe the capability
Send JSON or plain text (plain text becomes capability). Create a random, secret Idempotency-Key of 16–128 letters, digits, underscores or hyphens. Keep it: it is also your private result access token.
curl -i https://apifinder.online/api/v1/find \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: REPLACE_WITH_RANDOM_UUID' \
-d '{"capability":"Find an API that can translate PDF files",
"free_tier_required":true,
"auth_methods":["API key"],
"tier":"standard","max_results":5}'Optional fields: description, geography (where the API must work or what region the data covers), jurisdiction, programming_language, auth_methods, max_price (amount, currency, unit), latency, free_tier_required, commercial_use_required, data_residency, must_have, nice_to_have, exclude, max_results (1–10), tier, preferred_output_language, search_languages and max_price_usdc. Unknown fields are rejected. Maximum body: 16 KiB.
Mandatory vs screening. must_have, auth_methods, free_tier_required, commercial_use_required, data_residency and constraints stated in the capability text are mandatory: a candidate needs a quote from the provider’s own pages for each. geography, jurisdiction, max_price and latency exclude a candidate only if its documentation contradicts them; otherwise their status is reported. programming_language and nice_to_have never exclude.
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. Geography is independent of language: local markets are searched in their own languages (search_plan). Provider names, endpoints, prices and quotes stay verbatim; quote_translation and name_alias are convenience only.
2. Review the price and pay
Quick: 0.33 USDC. Standard: 0.51 USDC. Deep: 0.64 USDC. Add max_price_usdc to refuse with 422 price_exceeds_ceiling before any payment.
The price is fixed before payment: the calibrated variable cost of one research attempt for the tier (search, extraction, model, compute, database, storage, settlement), multiplied by the configured markup (3×, i.e. cost + 200%). Actual usage is recorded per request; there is no usage surcharge or automatic price true-up. Multiplier: 3×; minimum: 0.10 USDC.
The first request returns 402 with x402 v2 payment requirements in the body and the base64 PAYMENT-REQUIRED header. A free POST /api/v1/quote returns the same price for your input. Sign a USDC EIP-3009 authorization with an x402 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 });
// Spending policy before allowing automatic payment.
client.registerPolicy((_version, options) => options.filter(
p => p.network === "eip155:8453" && BigInt(p.amount) <= 510000n
));
const paidFetch = wrapFetchWithPayment(fetch, client);
const key = crypto.randomUUID(); // persist before submitting
const response = await paidFetch("https://apifinder.online/api/v1/find", {
method: "POST",
headers: { "Content-Type": "application/json", "Idempotency-Key": key },
body: JSON.stringify({ capability: "Find an API that can translate PDF files" })
});
const result = await response.json();Settlement is confirmed before research begins. On success, PAYMENT-RESPONSE contains the receipt.
3. Consume or retrieve the result
Example request ↗ · Complete response example (fictional demo) ↗
A completed request returns 200 with an API shortlist, normally within three minutes. Retrieve it again with the original key:
GET /api/v1/requests/{request_id}
Authorization: Bearer <original Idempotency-Key>Each entry of apis[] has provider_name and api_name (verbatim), website, documentation_url, pricing_url, capability_summary, quoted features and endpoints, and ten attributes — authentication, sdks, pricing, free_tier, rate_limits, geographic_restrictions, commercial_use, data_residency, availability, latency. Each attribute has a status:
- verified: value, source_url, verbatim quote and retrieval time from the provider’s own domain. Prices, limits, endpoints, auth and SDKs must appear literally in the quote.
- inferred: a labelled conclusion in
note. It never carries a value, so inferred prices, limits or auth methods cannot exist. - unknown: the retrieved documentation did not say. Value is null.
pricing_freshness gives the pricing page, retrieval timestamp, verbatim plan/unit/currency and a statement; unverified pricing says so and is never estimated. Also returned: requirement_checks, ranking_basis, known_limitations, evidence (URL, title, quote, source_type, first_party, source_language, retrieved_at), confidence, and top-level excluded_candidates with machine-readable rejection reasons.
Ranking. Candidates are kept only when capability relevance and every mandatory requirement are verified by a quote from the provider’s own pages. Survivors are ordered by: (1) number of optional requirements verified, (2) whether current pricing is verified from an official page, (3) whether a free tier or trial is verified, (4) number of verified attributes (auth, SDKs, limits, availability, etc.), (5) evidence-based confidence, then name. No hidden or model-generated score is used.
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. |
| 422 | Price above max_price_usdc | Nothing charged. Raise the ceiling or pick a cheaper tier. |
| 429 | Rate limit | Wait for Retry-After. |
| 503, paid: true | Research failure | Resend the same body and key with Authorization: Bearer <key> (or the same PAYMENT-SIGNATURE), up to twice, without a new payment. |
| 503, settlement_unknown | Uncertain settlement | Do not sign again. Preserve the request ID for reconciliation. |
| 503, not_configured | Service not yet accepting payments | Nothing charged. Try later. |
If the connection drops, resend the exact request with the same key and either the same PAYMENT-SIGNATURE or Authorization: Bearer <key>. Never create a new key just because you did not receive a response.
Health
GET /api/v1/health checks configuration only and never touches the database or providers. ?ready=1 adds a database probe that is CDN-cached for an hour. Please do not poll either more than once a minute.
Demo and live mode
Demo responses say mode: demo, contain fictional PDF-translation providers and never accept real payments (PAYMENT-SIGNATURE: demo:<key>). Live mode rejects demo signatures.
Privacy and terms
Live request text is sent to search and model providers; payment authorizations go to Coinbase Developer Platform. Don’t submit secrets or personal data. Results describe public documentation at retrieval time and are not a guarantee. See the Terms and Privacy Policy. API Finder is operated by Active Life Hub LLC.