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.

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.

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.