---
title: Verify
description: Sellers and gateways call one endpoint, designed to answer in under 50 ms.
canonical: https://tollrelay.com/docs/verify
lastmod: 2026-09-21
---

# Verify

Sellers and gateways call one endpoint, designed to answer in under 50 ms.

A seller runs a check before it serves. One call says whether the pass is good and what the spending limit has left. TollRelay never charges and never moves the money.

```http
POST https://pr-279-api.trlay.sh/verify
{ "identity_jwt": "…", "signature_input": "trlay=(…)", "signature": "trlay=:…:", "content_digest": "sha-256=:…:", "method": "POST", "target_uri": "https://data.example.com/search?q=…", "seller_id": "data.example.com", "endpoint": "/search", "amount_usd": "0.020", "rail": "x402", "settlement_ref": "eip155:8453:0x…" }
```

The answer says whether the pass is valid, which organisation and agent it belongs to, whether the organisation is verified, the spending limit remaining, and a receipt id to write into your history.

## The signature

The pass is valid only with the request the agent signed. Relay the request's `Signature-Input`, `Signature` and `Content-Digest` as they arrived, with the method and the full URL you received, beside the pass. The pass names the agent's key in `cnf.jkt`; the check verifies the signature against that key, inside its 30 second window, and accepts each nonce once. Check that the body matches `Content-Digest` before you call, because the check never sees the body.

A request with no signature answers 401 `signature_missing`, one that does not verify 401 `signature_invalid`, and one already seen 401 `signature_replayed`. Each carries a receipt and a `WWW-Authenticate: Bearer` challenge. The SDK's `gate()` does all of this for you.

## Offline

Check the pass against the public keys at `https://pr-279-api.trlay.sh/.well-known/jwks.json`, and the request's signature against the agent key whose thumbprint is the pass's `cnf.jkt`, read from the agent's DID document, and the key's bit on the status list the pass names. No call to the check is needed for that, so it does not depend on TollRelay being up. A nonce is refused twice only by the process that saw it: refusing a replay across your servers needs the online call.

## Online

Call `/verify` to check revocation, reputation and the spending limit remaining. For a paid call, send the payment reference in `settlement_ref`; TollRelay records it and does not move the money.

## A seller that charges by 402

Declare the `tollrelay-identity` extension in the 402 payment requirements. The agent sends `X-Trlay-Identity` with its payment, and echoes its pass and its signature fields in the extension's info. After the payment is made, call `/verify` with the reference from the payment response, as `network:transaction`, in `settlement_ref`. Check each signed request once: a second check of the same signature answers `signature_replayed`. TollRelay never pays and never takes payment.

The agent can append `requester` beside `identity_jwt` in the extension's `info`. Its `id` is a pseudonym of the person at the buyer who asked for the call, made for your host alone, and only the buyer can turn it back into a name. Its `aud` is your host in lower case. Pass the envelope to `/trust/evaluate` as it arrived; `/verify` does not take it. TollRelay records it in the buyer's history on a pass and on a refusal, and the answer to you never carries it. A value in any other shape is dropped and the decision is the same. Until request signatures are verified, the requester is recorded as you relayed it.

## Dispute a receipt

A seller can dispute a receipt from its own check. Send the buying organisation (the `org` claim of the pass, or the `org` field of the `/verify` answer) and one reason: `not_authorised_by_buyer`, `over_agreed_amount`, `not_as_described` or `other`. There is no free text. The call carries your verifier key and an `Idempotency-Key`.

```http
POST https://pr-279-api.trlay.sh/receipts/{rid}/dispute
```

The dispute is added to the buyer's history with a receipt of its own, and the original receipt is not changed. The same key with the same body answers the first result, and the same key with another body is a 409. A receipt that is not from your own check answers 404, whether or not it exists. An owner or admin of the buying organisation can also mark a purchase that should not have passed, and both show beside the purchase in their history and in the signed copy. This route is a proposal until it is accepted, so its path can change.

## Pricing

A check costs a seller nothing.

- Every check: free.
- Very high volume: a fair-use limit we agree with you.