Buyer documentation

Pay from your agent, per successful call.

The wallet stays on your machine. Start with the free sample, set explicit spending limits, and reuse one payment identifier for each logical request and all its network retries.

Endpoints and prices

All endpoints live on https://api.prospect402.com. Paid endpoints accept POST with a JSON body of {"url":"https://…"} and settle in USDC on Base mainnet (eip155:8453).

Endpoint	Price	Returns
`GET /v1/sample`	free	Immutable Stride Techworks snapshot in the current prospect-brief shape.
`POST /v1/signals`	$0.02	Site metadata, detected technologies, GEO readiness score, scanned URLs, and crawl warnings. No AI generation.
`POST /v1/prospect`	$0.10	Everything in Signals plus company claims with exact evidence, grounded opportunities, and a linked outreach opening.
`GET /health`	free	Service status and payment-configuration check.
`GET /openapi.json`	free	OpenAPI 3.1 description of every route and schema.
`GET /.well-known/x402`	free	x402 service manifest for discovery.

The payment flow

An unpaid request returns HTTP 402 with a PAYMENT-REQUIRED header describing the accepted network, asset, amount, and receiving address. Your client signs an authorization for exactly that amount and retries the identical request with a PAYMENT-SIGNATURE header. A successful response includes PAYMENT-RESPONSE with the settlement reference.

shell

curl -i -X POST https://api.prospect402.com/v1/signals \
  -H 'content-type: application/json' \
  -d '{"url":"https://www.stridetechworks.com/"}'

HTTP/2 402
payment-required: eyJ4NDAyVmVyc2lvbiI6...

Payment settles only for 2xx responses. Validation, robots, rate-limit, and model-validation failures return non-2xx and are never charged.

JavaScript buyer (@x402/fetch)

The official client wraps fetch, handles the 402 challenge, signs with your local key, and retries automatically.

buyer.mjs

import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.BUYER_PRIVATE_KEY);
const paidFetch = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }]
});
const response = await paidFetch("https://api.prospect402.com/v1/prospect", {
  method: "POST", headers: { "content-type": "application/json" },
  body: JSON.stringify({ url: "https://www.stridetechworks.com/" })
});
if (!response.ok) throw new Error(`Prospect402 ${response.status}: ${await response.text()}`);
console.log(await response.json());

First inspect the free sample. Cap the selected challenge at $0.02 for Signals or $0.10 for Briefs on Base mainnet (eip155:8453).

Retries and idempotency

Generate one payment identifier per logical request and reuse it for timeouts and transport retries. A settled retry returns the cached response without a second charge.
Reusing an identifier for a different route or URL is rejected.
Never retry validation, robots, rate-limit, or model-validation errors blindly; read the error body first.
Reports are cached for 24 hours. Repeating the same URL within that window returns the cached report.

Local stdio MCP bridge

The bridge exposes prospect402_sample, prospect402_signals, and prospect402_brief to any MCP client. Paid tools are disabled unless explicitly opted in, their per-call caps of $0.02 and $0.10 cannot be raised by configuration, and the bridge never logs wallet material.

mcp-client.json

git clone https://github.com/stvlley/prospect402.git
cd prospect402 && npm install

# MCP client configuration
{
  "mcpServers": {
    "prospect402": {
      "command": "npm",
      "args": ["run", "mcp"],
      "cwd": "/absolute/path/to/prospect402",
      "env": {
        "PROSPECT402_ALLOW_PAYMENTS": "true",
        "PROSPECT402_MAX_TOTAL_USD": "0.12",
        "PROSPECT402_WALLET_PRIVATE_KEY": "${BUYER_PRIVATE_KEY}"
      }
    }
  }
}