# Showing the record beside your listings

Version 2.

This page is for a catalog, a marketplace or a registry of paid agent endpoints that wants to show,
next to each listing, what paying that endpoint has delivered. Everything here is free, needs no
key, and can be mirrored. Nothing here can be bought: no seller can pay to change what the record
says about it, or where it appears.

## The whole market in one file

```bash
curl -sS https://api.teppi.xyz/v1/trust/index > teppi-index.ndjson
```

One json object a line, one line for every listed x402 endpoint, cached for an hour. Each line:

| Field | Meaning |
|---|---|
| `capability_id` | Teppi's id for the endpoint, stable across relistings |
| `url`, `method` | the endpoint as its listing names it; match your listings on these |
| `class`, `price`, `asset` | what the listing says it does and costs |
| `band` | `A` to `F`, or `UNRATED` |
| `tier` | what the band stands on; a letter only ever appears on a tier somebody paid for |
| `sample_count` | how many observations the card stands on |
| `computed_at` | when the card was worked out |
| `defects` | what the listing gets wrong before any payment, by name |
| `card` | the signed card, with the composite and every component behind it |

The composite is not in this file on purpose: it is published only beside its components, on the
card each line points at, so a number never travels without what it is made of.

## What to show, and how

- Show `band` with `tier` beside it, never the letter alone. A B on paid calls and a handshake
  that answered are different claims.
- Show `UNRATED` as unknown, never as a low grade. Most of the market has no paid record yet.
- Link the listing to https://teppi.xyz/endpoint/ followed by the `capability_id`, where every
  number carries the command that reproduces it.
- A small image for one listing: https://api.teppi.xyz/badge/ followed by the `capability_id`
  and `.svg`. It shows the strongest tier there is evidence for, and says UNRATED otherwise.

## One endpoint, at the moment of paying

A buyer holding a 402 asks about one url, with the payTo from the 402 if it has one:

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

The answer is signed. Where it carries `buy`, the same call can be bought through Teppi and paid
only once the answer passed its checks. Client code for this is at
https://api.teppi.xyz/docs/integrations.

## Offering pay on delivery beside a listing

Where the check answer carries `buy`, a buyer can pay for that same call through Teppi and be
charged only once the answer came back whole and matching the schema its seller published. On
2026-11-06 that held for 26,547 of 38,436 active listings, which carried 73% of the calls the
indexes count. A listing can say so, and send a buyer there:

```json
{
  "url": "https://api.teppi.xyz/v1/via/cap_01M1A51MCD19WV5TYP1BAA9ED3?network=ethereum",
  "method": "GET",
  "seller_price": "0.005000",
  "fee": "0.002000",
  "total": "0.007000",
  "asset": "USDC"
}
```

- The `url` answers with an ordinary x402 402, so any x402 client pays it unchanged.
  `teppi-client`'s `payOnDelivery` follows `buy` by itself.
- The fee is 10% of the seller's price, at least 0.002 USDC, and is taken only on a delivery that
  passed. A failed delivery costs the buyer nothing.
- From 0.05 USDC a call the 402 can also hold the buyer's money in the audited Base escrow until the
  answer passed, and above 0.05 up to 1.00 USDC it offers only that, while the escrow is open. Above
  1.00, or for a seller the record shows keeping money for nothing, no `buy` is offered.
- Every purchase leaves a receipt signed with the key named in
  https://api.teppi.xyz/.well-known/teppi-keys.json, which the buyer can check against the bytes it
  received.
- Ask the check again before showing `buy`: it is decided by the record at that moment, never by
  this page, and it can go away.

Two things a listing must not do with it. It must not rank a listing higher for having `buy`,
since `buy` follows from the record and nobody can pay for it. And it must not say a seller is
guaranteed: the guarantee is that the buyer is not charged for a failed delivery, not that a
delivery will succeed.

## Checking any of it yourself

Every card is signed with the key the record publishes at
https://api.teppi.xyz/.well-known/teppi-keys.json, over its RFC 8785 form. The method each number
is computed by is at https://api.teppi.xyz/docs/verification-method, and `npx teppi-check <url>`
runs the same free handshake against any endpoint from your own machine.

## Changelog

### 2

| Change | Reason |
|---|---|
| Offering pay on delivery beside a listing: the `buy` field, its fee, escrow, and what a listing must not claim | A listing can now spare its buyers a failed delivery, and one that ranks by `buy` or calls a seller guaranteed would be selling what the record cannot |
| Versions are a plain count from here | A dotted version reads as a day |

### 2026.09.1

| Change | Reason |
|---|---|
| First version: the index file, what to show and how, the badge, and the check at the moment of paying | A catalog showing the record beside thousands of listings needs one file rather than a call per listing, and the words that keep UNRATED from reading as bad |
