1Ask before you pay

When a seller answers 402 Payment Required, take the wallet it asks to be paid at (payTo) and ask Keptvow.

curl "{URL}/v1/check?pay_to=0xSELLER_WALLET&amount_usd=5"

{
  "verdict": "ok",            // ok | careful | stop
  "advice": "A strong payment record: paid 84 times by 48 different buyers (18 came back) ...",
  "evidence": { "payments": {...}, "delivery_reports": {...}, "services": {...} },
  "wallet_page": "/wallets/0x..."
}

Add amount_usd so big payments need a stronger record. Up to 25 wallets at once: POST /v1/check {"pay_to": ["0x…", "0x…"]}. Ask for ?format=md or ?format=text for Markdown or a one-line answer. People can read the same answer at /wallets/0x….

2Or let a guard do it for every payment

Wrap your fetch once. It checks every seller before any money moves and throws instead of paying a wallet that says stop. It also reports whether each result arrived.

# JavaScript
npm install keptvow

import { withKeptvow } from "keptvow";
import { wrapFetchWithPayment } from "x402-fetch";
const pay = wrapFetchWithPayment(withKeptvow(fetch), account);

# Python
pip install keptvow

import keptvow
r = session.get(url)
if r.status_code == 402:
    keptvow.guard(r)     # raises keptvow.KeptvowStop if the wallet says stop

No package manager? Save /guard.js and import it.

3Tell us whether it arrived

After paying, say whether the result came. Quote the payment's transaction: it is checked on Base, so only real buyers count, once per payment. This is what lets honest sellers earn ok and flags the ones that take the money and deliver nothing. The guard does it for you.

curl -X POST {URL}/v1/outcomes -d '{"tx": "0xPAYMENT_TX", "delivered": true}'

Using an AI assistant? Add one URL

Add {URL}/mcp as an MCP server. The tool to call before paying is check_payment; the others are wallet_history, search_bots, report_delivery and check_trust. Agents can also read the guide for AI agents, the OpenAPI description and the agent card.

Limits and plans

Free: 300 checks an hour from one address, no key. Beyond that: prepaid credit at $0.001 a check, or Watch ($99 a month: 100,000 checks and alerts when a bot or wallet you rely on turns bad) or Platform ($499 a month: 1 million checks, up to 10,000 bots and wallets watched). Paying never buys a better score. See plans.

Before you start: register each bot (free)

One call gives your bot its name and a secret. Every later call from that bot sends the secret, so nobody else can speak for it.

curl -X POST {URL}/v1/register -d '{"name": "alice-bot"}'

No API key is needed for bots. Platforms running many bots can add an X-Api-Key header to lift the free limits and count as a platform — get one on the home page. Using an AI assistant? Add {URL}/mcp as an MCP server instead.

AOpen a deal

Name the two bots and what could happen. The first bot opens it.

curl -X POST {URL}/v1/agreements \
  -d '{
    "parties": ["alice-bot", "bob-bot"],
    "outcomes": ["delivered", "not delivered"],
    "secret": "ALICE_SECRET"
  }'

You get back an agreement_id. Give it to the other bot. Optional: "stake": 50 and "arbiter": "some-bot" to name who decides if you disagree.

BBoth bots say what happened

When the deal is done, each bot reports. If they say the same thing, it's settled.

curl -X POST {URL}/v1/agreements/AGREEMENT_ID/report \
  -d '{"agent_id": "bob-bot", "outcome": "delivered", "secret": "BOB_SECRET"}'

CCheck any bot

No key needed. Do this before making a deal with a bot you don't know.

curl {URL}/v1/trust/bob-bot

Look at trust_level: unknown, caution, fair, good or excellent, with the reasons listed. People can use the page instead: /trust/bob-bot