Setting

Ruth asks her assistant: book me a GP appointment this week, no more than £80, English-speaking doctor. Her agent has GeraNexus installed. GeraClinic advertises a /.well-known/gera-nexus.json descriptor. This post is the sketch of what happens next.

1. Discover

The agent fetches /.well-known/gera-nexus.json from any candidate marketplace. The descriptor lists supported actions (negotiate, book, pay, etc.), consent scopes, escrow support, dispute endpoints and rate limits. GeraClinic returns booking-capable; other services may return only quote-capable.

2. Negotiate

The agent sends a negotiate request with Ruth’s constraints — price cap, time window, language, insurance status. GeraClinic responds with a set of candidate slots, each with a quoted price, provider identity, consent scope required and a short-lived negotiation_id. Nothing is booked yet.

3. Consent scoping

Before the agent can move to book, it has to produce a consent token signed by Ruth that covers the specific combination of action, scope and monetary cap. This is the’step most likely to require user interaction — the assistant shows Ruth a single quote-card with the provider, price, time and a one-tap confirm. The consent token is bound to the negotiation_id.

4. Book

With a valid consent token, the agent sends book. GeraClinic reserves the slot and returns a booking_idplus a cryptographically-signed booking receipt. At this point the slot is held but not paid for.

5. Pay (with escrow)

The agent calls pay. Payment can route through GeraCash, Stripe, or a user-selected rail. For services that support it (GeraClinic does), the payment can go into escrow and release on verify-completion rather than on confirm. This is the primitive that makes disputes cheap: the money has not yet moved when the dispute window opens.

6. Verify-policy

Before a user transacts with a marketplace they never chose, the agent should verify the cancellation / refund / dispute policy signed by the marketplace. GeraNexus defines a standard policy schema: max cancellation window, refund percentage ladder, dispute SLA. The agent checks these against the user’s preferences (which the user set once, globally) and aborts if they do not match.

7. Confirm

Once paid, GeraClinic returns a confirmed booking with a calendar invite, joining instructions, and a completion_tokenthat will be used by the verification step.

8. Verify-completion

When the consultation ends, GeraClinic emits a signed completion receipt. Ruth’s agent can verify the receipt and release the escrow. If Ruth signals that the service was not rendered (or was inadequate) the agent routes to dispute instead and the escrow holds.

9. Dispute

The dispute endpoint routes to human arbitration. The protocol does not try to automate dispute judgements — it standardises the request shape, the evidence payload, and the SLA. Gera operates an arbitration panel for Gera-network disputes; third-party marketplaces bring their own arbitrators.

What this looks like over the wire

Every call is JSON-RPC 2.0 over HTTPS. Auth is OAuth 2.1 with a tokenised consent binding specific to the action being taken. Receipts are Ed25519-signed. There is no proprietary transport because there doesn’t need to be — HTTPS + JSON-RPC is sufficient.

Why this shape

Discover before negotiate — protocol version negotiation + capability check before any commitment.
Consent scoped to the negotiation, not to the agent — the user can’t be "consented" indefinitely.
Escrow as a first-class primitive — makes the dispute loop cheap.
Verify-completion separate from confirm — solves the "paid for something that never happened" class of fraud.

What’s not in the sketch

We have left a lot out: refund ladders, partial completion, tip semantics, multi-party bookings, subscriptions, chained transactions that pay multiple parties. Each gets its own spec chapter. The goal of this post is to show that the happy path is tractable.

Where to read more

The full draft spec lives at /spec. Open questions go up on this blog as they come. Integration examples — wrapping existing Gera MCPs — will be published alongside the public v0.1 milestone.