# Check before you pay, in the client you already use

Version 9.

Every snippet below asks the Teppi record one question at the moment a 402 arrives, before a
payment is signed: what paying this endpoint, and whoever it pays, has actually delivered. The
answer is signed, free, needs no key, and is cached for a minute. A url the record has never seen
is answered UNRATED, never as bad, and is put in line for a free handshake.

Nothing here sends your request body, your wallet or your payment anywhere. The one thing that
leaves is the url you are about to pay, and the payTo address from its 402 when you pass it.

## The official x402 client

`@x402/core`'s client calls `onBeforePaymentCreation` before it signs anything. Returning
`{ abort: true, reason }` stops the payment. `teppiHook` is that hook, and it reads the url and
the payTo from the 402 itself.

```bash
npm install teppi-client
```

```ts
import { x402Client } from '@x402/core/client';
import { teppiHook } from 'teppi-client';

const client = new x402Client()
  .register('eip155:*', evmScheme)
  .onBeforePaymentCreation(teppiHook({ minBand: 'C' }));
```

`@x402/fetch` and `@x402/axios` wrap this same client, so the hook covers them too: build the
client as above and hand it to the wrapper you already use.

The hook also refuses a 402 asking more than five times what the endpoint's last 402 asked, in the
same token, since the client signs whatever amount a server names. `{ maxOverUsual: 2 }` tightens
it and `{ maxOverUsual: false }` turns it off.

## Any client that takes a fetch

`beforeYouPay` wraps a fetch. On a 402 it asks the record first; when the policy refuses, the
402 becomes a 403 that says why, before anything is signed. It works for any 402, x402 or MPP,
since it reads only the status and the url.

```ts
import { beforeYouPay } from 'teppi-client';

const guarded = beforeYouPay(fetch, { minBand: 'C', unrated: 'allow' });
```

The default policy refuses a listing the record shows failing before payment, and a band below
the one you name. UNRATED is paid by default, since most of the market has no paid record yet.
Pass `policy` for your own rule; it receives the whole answer.

## Paid only on delivery

Where the answer carries `buy`, the same call can be bought through Teppi: the seller is paid by
us, the answer is checked, and you are charged only once it passed. The price is the seller's plus
a 10% fee, at least $0.002.

```ts
import { beforeYouPay } from 'teppi-client';

const guarded = beforeYouPay(fetch, { payOnDelivery: true, publish: true });
```

`publish` is off unless you set it. Set, the call you bought goes into the public record, bytes
and all, under one opaque name for your wallet. It counts toward what the next buyer reads about
that seller, and it can pull a seller's published figures down but never push them up, so a
seller buying its own endpoint gains nothing by it. Left off, nothing you sent is published: only
salted commitments that you alone can open.

From a total of $0.05, and up to $1.00, the same 402 can also offer `auth-capture`: your money
waits in the audited Base escrow, captured for Teppi's treasury only once the answer passed and
handed back otherwise, and you can take it back yourself after 30 minutes whatever Teppi does. The
official client pays it with `AuthCaptureEvmScheme`, and since it prefers paying after the fact
whenever both are offered, `preferEscrow` keeps the escrow terms alone:

```ts
import { x402Client } from '@x402/core/client';
import { AuthCaptureEvmScheme } from '@x402/evm/auth-capture/client';
import { preferEscrow } from 'teppi-client';

const client = new x402Client()
  .register('eip155:8453', new AuthCaptureEvmScheme(signer))
  .registerPolicy(preferEscrow);
```

## One GET, from any language

```bash
curl -sS 'https://api.teppi.xyz/v1/check?url=https%3A%2F%2Fseller.example%2Fv1%2Fprice&pay_to=0x2a462db85807f0ff497ddd15f5978317d079a3a1'
```

```python
import requests

answer = requests.get(
    "https://api.teppi.xyz/v1/check",
    params={"url": url, "pay_to": pay_to},
    timeout=5,
).json()
if answer["defects"]:
    raise RuntimeError(answer["defects"][0]["says"])
```

Read `band` with `tier` beside it: a letter is only ever given on a tier somebody paid for, and
UNRATED means unknown, not bad. `defects` says what the listing gets wrong before any payment,
`payee` what the record knows about whoever gets paid, and `buy` how to pay only on delivery.

## As a tool your agent can call

The same answer is the `check_grade` tool on Teppi's MCP server, with `search_capabilities` to
find an alternative that has been paid and checked.

```bash
claude mcp add --transport http teppi https://api.teppi.xyz/mcp
```

```json
{ "mcpServers": { "teppi": { "url": "https://api.teppi.xyz/mcp" } } }
```

The second is for a client that reads a json config, such as Cursor's `.cursor/mcp.json`. A
skill file that makes an agent ask before it pays is at https://api.teppi.xyz/docs/skill.

## In an agent framework

`checkTool()` is the same check as one tool: a name, a JSON schema and the call. It answers
`pay` and `because` from the policy the guards use, the grade, what is wrong with the listing,
and `buy` where Teppi can buy it charged only on delivery. Each snippet below was typechecked
against the library named.

Vercel AI SDK (`ai` 7):

```ts
import { jsonSchema, tool } from 'ai';
import { checkTool } from 'teppi-client';

const teppi = checkTool();
const checkBeforePaying = tool({
  description: teppi.description,
  inputSchema: jsonSchema<{ url: string; method: 'GET' | 'POST' }>(teppi.parameters),
  execute: teppi.execute,
});
```

OpenAI Agents SDK (`@openai/agents` 0.21):

```ts
import { tool } from '@openai/agents';
import { checkTool } from 'teppi-client';

const teppi = checkTool();
const checkBeforePaying = tool({
  name: teppi.name,
  description: teppi.description,
  parameters: teppi.parameters,
  strict: true,
  execute: (input) => teppi.execute(input as { url: string; method: 'GET' | 'POST' }),
});
```

LangChain (`@langchain/core` 1.3):

```ts
import { tool } from '@langchain/core/tools';
import { checkTool } from 'teppi-client';

const teppi = checkTool();
const checkBeforePaying = tool(
  async (input: { url: string; method: 'GET' | 'POST' }) =>
    JSON.stringify(await teppi.execute(input)),
  { name: teppi.name, description: teppi.description, schema: teppi.parameters },
);
```

## Your whole fleet at once

Send every paid endpoint your agents call, up to 200, and get each one looked up the way a check
is, then added up by the address each one pays. One address often stands behind many origins, so
a list that looks spread out can be one operator.

```bash
curl -sS https://api.teppi.xyz/v1/exposure \
  -H 'content-type: application/json' \
  -d '{"dependencies":[{"url":"https://seller.example/v1/price","calls_per_month":3000},"https://other.example/v1/lookup"]}'
```

Each line carries a `standing`: `took_the_money` (a paid call settled and nothing came back),
`listing_mismatch`, `lettered`, `paid_no_letter`, `handshake_only` or `not_in_record`. The
last two mean unknown, and unknown is never counted as a failure: the spend totals keep
`monthly_spend_not_yet_measured` apart from `monthly_spend_where_the_record_shows_a_failure`. Pass
the `pay_to` from a 402 and `pay_to_seen_before` says whether this seller has been seen paying
that address. The answer is signed like a check, and the same report is the `check_exposure` tool.

## Amazon Bedrock AgentCore

AgentCore payments calls `pre_sign_policy` at the moment before it signs, in both the Strands
plugin and the LangGraph middleware, and signs only when it returns exactly `True`; anything else,
an exception included, blocks the payment. The Python `teppi-client` is that policy. It reads the
url and the payTo out of the 402 itself, whether x402 version one, version two or an MPP challenge.

```bash
pip install teppi-client
```

```python
from bedrock_agentcore.payments.integrations.config import AgentCorePaymentsPluginConfig
from teppi_client import pre_sign_policy

config = AgentCorePaymentsPluginConfig(
    payment_manager_arn=PAYMENT_MANAGER_ARN,
    user_id="user-123",
    payment_instrument_id=INSTRUMENT_ID,
    payment_session_id=SESSION_ID,
    region="us-west-2",
    pre_sign_policy=pre_sign_policy(min_band="C"),
)
```

It refuses a payee whose paid calls settled with nothing usable back, a listing the record says is
broken, a letter below `min_band`, and an amount more than five times what the endpoint last asked.
An unrated seller is paid, since unknown is not bad. If the record cannot be reached the payment goes
ahead, unless `when_unreachable="refuse"`. The session budget still applies on top: it bounds how much
is spent, and the policy decides who it is spent on.

AgentCore Gateway takes Teppi's MCP server as a target the same way it takes the Coinbase x402
Bazaar, so an agent that finds a paid endpoint through the Bazaar can ask what it delivered before it
pays:

```bash
agentcore add gateway-target --gateway MyGateway --name TeppiRecord --endpoint https://api.teppi.xyz/mcp
agentcore deploy
```

```python
import boto3

boto3.client("bedrock-agentcore-control").create_gateway_target(
    gatewayIdentifier="your-gateway-id",
    name="TeppiRecord",
    description="What paying an x402 endpoint has delivered, checked by paid calls",
    targetConfiguration={"mcp": {"mcpServer": {"endpoint": "https://api.teppi.xyz/mcp"}}},
)
```

No outbound authorization is needed: the server is free and needs no key.

## Cloudflare agents

An agent built on Cloudflare's Agents SDK pays an MCP tool through `withX402Client`, whose
`callTool` asks a confirmation callback first and pays only if it resolves `true`. The callback is
handed the payment terms and never a url, so `teppiConfirm` goes by who gets paid, and by the
server's own url when you pass it.

```ts
import { withX402Client } from 'agents/x402';
import { teppiConfirm } from 'teppi-client';

const client = withX402Client(mcpClient, { network: 'base', account });
await client.callTool(teppiConfirm({ server: 'https://tools.example/mcp', minBand: 'C' }), {
  name: 'get_price',
  arguments: { symbol: 'BTC' },
});
```

A Worker that pays an HTTP endpoint with an x402 fetch wraps that fetch in `beforeYouPay`, as above.
Cloudflare has announced wallet allowlists for agents; until they are documented, the payout list in
the next section, `?format=plain`, is what to feed one.

## Inside the wallet's own signing policy

An x402 payment on Base is an EIP-3009 `TransferWithAuthorization`, and the address it pays is its
`to` field. Wallet policy engines can refuse to sign typed data by that field, so the record can
reach a payment even when nothing in the agent asks first. The list is payouts where at least three
paid calls of ours settled and brought back nothing usable and the 95% lower bound of that share is
at least 5%, or where paid answers our checks found wrong, with those that brought nothing, have a
lower bound of at least half; each entry says which in `why`, carries its evidence and says how many
origins stand behind the address, since a refusal reaches all of them. `?format=plain` names Solana
payouts too; the CDP and Privy formats read an EIP-3009 `to` and so carry Base payouts only.

```bash
curl -sS https://api.teppi.xyz/v1/policy/payouts
curl -sS 'https://api.teppi.xyz/v1/policy/payouts?format=plain'
```

- **Coinbase CDP policy engine.** `?format=cdp` returns two `reject` rules, one for
  `signEvmTypedData` and one for `signEndUserEvmTypedData`, with an `evmTypedDataField` criterion
  on `to` (at most 300 addresses). Add them to the project policy that covers the agent's wallets.
- **Privy.** `?format=privy` returns a `DENY` rule on `eth_signTypedData_v4` over the message's
  `to` (at most 100 values). For a list that changes, keep the addresses in a condition set and point
  the rule at it with `in_condition_set`, so updating it needs no new policy.
- **Turnkey, Fireblocks and others.** Read `?format=plain` into whatever list the policy takes, or call
  `/v1/check` with `pay_to` from a co-signer callback.

### A pack: refuse the listed, cap the unmeasured

Unknown is not bad, but it is unknown, and a wallet owner may want a smaller limit there than for a
payee the record has paid and graded. Add `cap`, in USDC, to either format:

```bash
curl -sS 'https://api.teppi.xyz/v1/policy/payouts?format=cdp&cap=0.05'
curl -sS 'https://api.teppi.xyz/v1/policy/payouts?format=privy&cap=0.05'
curl -sS 'https://api.teppi.xyz/v1/policy/payouts?list=measured'
```

A measured payee is one behind an endpoint holding a paid letter now, less any the refusal list
names; `list=measured` returns them one a line, and is never served as a rule that refuses them.

- **CDP** gets the two refusals above and two more `reject` rules whose one criterion holds a
  `value` above the cap and a `to` not in the measured list. The conditions of one criterion
  must all hold for the rule to apply.
- **Privy** gets three rules, since Privy denies when any rule denies and otherwise allows only
  what a rule allows: `DENY` the refused, `ALLOW` a `value` at or under the cap, and
  `ALLOW` a `to` in the measured list. Past 100 measured payees that last rule names
  `in_condition_set` with `your-condition-set-id`: make a condition set, fill it from
  `list=measured`, and put its id there. A policy with only these rules denies every other
  signing method, so add the rules your wallet already needs beside them.

Before relying on either, sign one payment just under and one just over the cap and see each
answer: Privy compares a value as the request writes it, and neither platform documents how a
decimal string in the message meets the value in a rule.

These rule shapes were written from each platform's documentation on 2026-10-28 and 2026-11-06.
Check them against the current documentation before applying. A payment to an address on neither
list is capped, never refused: unknown is not bad.

## Told when a card falls

Register an https receiver and the endpoints to watch. Before anything is kept, the receiver is
posted a challenge and must echo it, so nobody can point notices at a url that did not ask. The
answer carries a token, shown once, that reads or stops the watcher.

```bash
curl -sS https://api.teppi.xyz/v1/watchers \
  -H 'content-type: application/json' \
  -d '{"url":"https://you.example/teppi","watch":["https://seller.example/v1/price"]}'
```

The receiver answers the challenge and takes only notices that verify against the key that signs
the cards:

```ts
import { noticeReceiver } from 'teppi-client';

export const POST = noticeReceiver(async (notice) => {
  console.log(notice.capability_id, notice.change, notice.from, '->', notice.to);
});
```

A notice names the card it is about, so nothing has to be taken from the notice itself. Read a
watcher back with `GET /v1/watchers/{watcher_id}` and stop it with `POST /v1/watchers/stop`,
each with the token as a bearer.

## Checking that Teppi said it

Every answer is signed by the key the record publishes for checks, and never by the key that signs
scorecards.

```ts
import { check, publishedKeys, verify } from 'teppi-client';

const answer = await check('https://seller.example/v1/price');
const result = await verify(answer, await publishedKeys());
```

## Changelog

### 9

| Change | Reason |
|---|---|
| The payout list names a payout whose paid answers were mostly wrong (`why: wrong`), and Solana payouts in plain and json | sniperx answered 15 of 16 paid calls with a SOL price frozen at 176.188 while four exchanges read 93 to 102, and was on no list: one rule counted only calls with nothing usable back, and the query read Base payouts alone |

### 8

| Change | Reason |
|---|---|
| A pack for CDP and Privy: the refusal list plus a cap on payees no paid letter stands behind, and `list=measured` | Refusing the worst payees left every unmeasured one at the wallet's full limit; a smaller limit there is what a wallet owner can set without calling unknown bad |

### 7

| Change | Reason |
|---|---|
| Amazon Bedrock AgentCore: the Python `teppi-client` as AgentCore's `pre_sign_policy`, and Teppi's MCP server as a Gateway target beside the Bazaar; Cloudflare agents: `teppiConfirm` for `withX402Client` | AgentCore checks a session budget and Cloudflare asks a callback before paying, and neither looked at who was being paid. The urllib snippet this replaces sent Python's default user agent, which the edge in front of the api refuses |

### 6

| Change | Reason |
|---|---|
| Inside the wallet's own signing policy: `/v1/policy/payouts` as plain text and as CDP and Privy rules, and a check before paying in an AgentCore agent | A spending limit bounds the loss and never looks at the payee; the engines that sign for agents can refuse a payee, and had no list to refuse |

### 5

| Change | Reason |
|---|---|
| In an agent framework: `checkTool()` with snippets for the Vercel AI SDK, the OpenAI Agents SDK and LangChain, each typechecked against the library; the hook refuses a 402 asking more than five times the endpoint's last price | Agents are built in frameworks more than on the bare x402 client, and a client signs whatever amount a 402 names |

### 2026.09.4

| Change | Reason |
|---|---|
| Paying in escrow, with `AuthCaptureEvmScheme` and `preferEscrow` | A buyer's money can now wait in the audited escrow until the answer passed, and the official client picks paying after the fact unless told otherwise |

### 2026.09.3

| Change | Reason |
|---|---|
| Your whole fleet at once (`POST /v1/exposure`), and told when a card falls (`POST /v1/watchers` with `noticeReceiver`) | A fleet checked one url at a time never sees that many of its dependencies pay one address, and notices existed with no way to ask for them |

### 2026.09.2

| Change | Reason |
|---|---|
| `publish: true` beside `payOnDelivery`, and what publishing does and does not do | A buyer who wanted its call to count had to set a header by hand on the paid retry, which a wrapper hides |

### 2026.09.1

| Change | Reason |
|---|---|
| First version: the official x402 client, any fetch, paid only on delivery, one GET from any language, MCP, and checking the signature | Every piece existed, and nothing said where it goes in the client a developer already has open |
