# TollRelay for agents

One pass for every agent that spends. The check at the toll, not the charge. Three calls, then one header on every request.

## The three calls

1. `POST https://api.trlay.dev/identity/orgs` with name, handle, region (eu or us) and a work email. It carries an Idempotency-Key and needs no API key. Returns the organisation id and sends the sign-in link to the work email; signing in is how you get the API key the next two calls present.
2. `POST https://api.trlay.dev/identity/machines` with the org id and a label. Issues a pass: the identity id and its signing key, once.
3. `PUT https://api.trlay.dev/mandates/<mid>` with usd_per_day, usd_per_call_max and the sellers allowed. An approver signs it on the trusted surface.

## On every request

Present `X-Trlay-Identity: <JWT>`. Your mandate is in the token; do not exceed it. The SDK enforces it client-side before the request leaves. This header is the interim until the SDK signs each request per RFC 9421.

## For sellers

Verify offline: resolve the organisation DID document, check the credential against the trust list at `https://api.trlay.dev/.well-known/trlay-trust-list.jws`, and check its status against the status list. Verify online by running the gate at `POST https://api.trlay.dev/trust/evaluate`, which answers a decision, the evidence by class and a receipt id in under 50 ms. `/verify` stays as an alias with the v3 body until Welila cuts over.

## The record

Read the record at `GET https://api.trlay.dev/record`: mandate receipts, settlements, wallet activity and verifier events, each with its receipt id, newest first. Add `month=YYYY-MM` for one calendar month in UTC. `/spend` is the former name, kept for one version, and answers the same.

## Discovery

OpenAPI: `https://api.trlay.dev/openapi.json`. JWKS: `https://api.trlay.dev/.well-known/jwks.json`. MCP: `https://api.trlay.dev/mcp` with tools identity, mandate and spend, described at `https://api.trlay.dev/.well-known/mcp/server-card.json`. How a bearer credential is presented: `https://api.trlay.dev/.well-known/oauth-protected-resource`.

## Paying sellers

TollRelay never pays. When a seller answers 402 and names `tollrelay-identity` in its extensions, send the identity with the payment; the seller runs the gate, and the settlement reference lands in your record.