Weigh one payment before sending it
preflight_paymentCall this immediately before sending a payment, every time — not once per counterparty. It weighs THIS payment (the amount, the chain, the endpoint) against what the address has actually done: the price the seller themselves published for that endpoint, the address that endpoint names as its payee, the largest payment this address has ever received, and whether it has ever been paid on the chain you are about to use. Answers one of three verdicts. nothing-against-it means every check ran and none objected — it is NOT a statement that the payment is safe, because nothing here can see what the payment is for or what you agreed. look-first means at least one thing we could READ does not match, and the findings say which; a check that could not run never produces it, it produces cannot-say. cannot-say means we did not read enough to have an opinion, and must never be read as the first. Free. Give as much of amountUsd, chain and resource as you have: each one left out is a check that did not run, and the answer says so rather than passing. THE ENDPOINT’S OWN WORD OUTRANKS THE CATALOGUE. Where we have probed the endpoint, againstEndpoint.price carries what it actually demanded and when, ranked above the seller’s listing and above what the address has been paid, with every disagreement between the three kept rather than resolved — live-price-differs-from-listing means the price has MOVED and the live figure is the one to pay, and quoted-payee-is-not-the-one-being-paid means the endpoint asks to be paid somewhere other than where you are sending. live-price-not-comparable means the two prices are in different tokens or one is unnamed, so they were NOT compared rather than compared and found to agree. againstQuote IS THE FIELD TO BRANCH ON: exact-match, below-quote, above-quote or unknown. below-quote is not a pass — the endpoint has said what it wants for THIS call and the payment is under it, so it will not buy the thing unless the terms allow a partial payment, which we cannot see; it is a REVIEW and never a refusal. Paying less than the CATALOGUE’s price is a different question and stays neutral, because a directory entry may price a different unit and was written once. FINDINGS WORTH KNOWING BY NAME. below-listed-price means the payment is under half the seller’s published price: ordinary, not an objection, and NOT a confirmation of the amount either, because the listing may price a different unit or tier — it is neutral and cannot improve the verdict. network-not-comparable means the listing names a network we could not resolve, so the chains were not compared rather than compared and found to agree. A CAIP-2 id and a chain name are resolved through one shared map, so eip155:8453 and base are the same network here and in check_action; they used to disagree.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | The address you are about to pay. | |
| chain | No | The chain you are about to send it on, e.g. base, polygon, solana. | |
| resource | No | The http(s) URL of the endpoint you are buying, where there is one. This is the sharpest check available: its catalogue entry carries the seller’s own price and their own payee address. | |
| amountUsd | No | What you are about to send, in US dollars. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| says | Yes | The verdict in one sentence, naming what did not match. Written to be shown to a person deciding whether to go ahead. | |
| check | No | The free counterparty check for this address. | |
| limits | No | What this check cannot establish, in full. Quote it whenever you quote the verdict: a clean answer here is the absence of an objection, never a guarantee about the payment. | |
| listing | No | The seller’s own catalogue entry for the resource, where there is one — their word, written once, possibly months ago. | |
| verdict | Yes | `nothing-against-it` means every check ran and none objected — NOT that the payment is safe. `cannot-say` means too little was read to have an opinion, and must never be read as the first. It is also the answer when nothing contradicted the payment but a check could not run, because reporting our own gap as a clean result would be the worst of the three. | |
| findings | No | Every check that ran, each with the record behind it and its own `tone` and `kind`. NOT only the ones that objected: a `tone` of `good` is a check that MATCHED, so reading this array’s length as a count of problems overstates them. Bucket on `kind` — `fact` and `signal` were established, and `unknown` means we could not see, which never counts as something standing against the payment. | |
| proposal | No | Your payment as we understood it: payee, amount, chain and resource. Null where too little was given to form one. Check it before reading the verdict, which is about THIS proposal and no other. | |
| received | No | What you told us, read back, so a typo is visible. | |
| verdicts | No | What each verdict word means, so a caller never has to guess. | |
| observations | Yes | Every check that ran, including the ones that could not: a field you left out appears here as a check that did not run, rather than as silence. | |
| againstEndpoint | No | WHAT THE ENDPOINT ITSELF DEMANDED, from the 402 it answered our own unpaid request with, and how that compares. `price.againstQuote` is the one word to branch on — `exact-match`, `below-quote`, `above-quote`, `unknown` — and `below-quote` is NOT a pass: the endpoint stated what it wants for this call and less than that does not buy it unless its terms allow a partial payment, which we cannot see. `price.evidence` ranks the three parties who can state this endpoint’s price — the endpoint’s own quote first, the catalogue second, what the address has actually been paid third — and `price.lead` names the one to act on. `price.disagreements` keeps every conflict between them with BOTH figures: a price that has moved is a finding neither source alone can show, and we never resolve it into a single number. `price.liveQuoteMatchesCatalogue` is true, false, or NULL FOR NOT COMPARABLE, which is not the same as not matching — a 402 states an amount in the asset’s smallest unit and never its decimals, so two raw figures are only the same kind of number when the token is the same; `liveQuoteMatchesCatalogueWhy` says which half is missing. `quoted` is false where we have never probed the endpoint, which is our gap and not evidence against the payment. |