Core concepts

Eight terms the rest of these docs assume. Skim once and everything else reads faster.

Settlement#

One payment, on one chain, in one transaction: a payer, a payee, an amount, a token, a block time. It is the atom of the index and the thing every aggregate is made of.

A settlement is not the same as a USDC transfer. Most transfers are not x402 payments, and one transaction can contain several transfers that add up to one payment. What makes a transfer a settlement is evidence — see confidence below.

Entity#

A wallet address, plus whatever Roundhouse has been able to resolve about it: an ERC-8004 agent id, an ENS name, a display name, a service it appears to run. Entities are not accounts you create; they are addresses observed transacting, annotated after the fact.

The same wallet can be an agent (paying) and a merchant (being paid). /agents/<wallet> and /merchant/<wallet> are two views of one entity, not two records.

payTo#

The address a service asks to be paid at, quoted in its 402 response. It is the join between a listing and the ledger: the catalog says "pay me here", and settlements to that address are what prove anyone did.

A payTo is not necessarily the merchant's own wallet — see fee proxy.

Facilitator#

The service that verifies a signed payment authorization and broadcasts it on-chain. It pays the gas, which is why an agent can hold USDC and no ETH and still transact.

The facilitator is the transaction's sender, not a party to the payment: the payer and payee are inside the signed authorization, so a facilitator cannot redirect funds or take a cut it was not granted. In the index it appears as via_facilitator — an attribution, drawn beside the edge rather than on it.

Three things "no facilitator" can mean, and the index distinguishes them:

• self — the payer submitted their own transaction and paid their own gas.
• unattributed — a third party relayed it and we have not identified them yet.
• A raw address — a relayer we do not recognise, stored as itself so it stays groupable.

Fee proxy#

A contract that receives a payment and forwards it, splitting off a fee, in the same transaction. Buyer → proxy → merchant, one transaction, two transfers.

This matters because a naive indexer records the proxy as the payee and the gross amount, and the merchant then never appears at all. Roundhouse collapses the chain so payee is the merchant and the fee is recorded separately. If a figure looks like it belongs to an intermediary rather than a business, this is usually why.

Scheme#

How a payment is proved. Today that means exact: an EIP-3009 TransferWithAuthorization, signed over the token contract's own EIP-712 domain, for an exact amount. The scheme name appears in the 402 response, and a client that does not recognise it must not pay.

See schemes and networks.

Confidence#

How sure we are that a row is really an x402 payment. It is three-valued, and blending the three is the most common way to get a wrong number:

/stats leads with the verified population and discloses the rest in words. Per-entity rollups still blend all three, and the docs say so where it matters.

Rollup#

A pre-computed aggregate. mv_entity_rollups (per wallet), mv_entity_daily (per wallet per day), mv_global_daily (per day, site-wide). They exist because aggregating tens of millions of settlement rows on demand does not fit in a request.

They refresh on a schedule and therefore trail the chain. Read paths fold in the newer settlements so a page is current even when the view behind it is not.

Agent card#

A JSON document describing an agent: name, description, capabilities, endpoints, protocols. An ERC-8004 registration points at one by URI.

The card is a claim, signed by the wallet that owns it. It is not evidence of competence — that is what the settlement record is for. See agent cards.