Protocol Specification · GeraNexus v1

GeraNexus Agentic Commerce Protocol

Spec version 0.1.0

Agentic commerce protocol — the transactional layer AI agents use to negotiate, book, pay, cancel, refund, dispute, and verify completion across all Gera verticals and any third-party service that publishes a /.well-known/gera-nexus.json descriptor.

View OpenAPI specJoin waitlist

Capabilities

discover
Enumerate available service types and check availability windows
negotiate
Exchange constraints and receive binding price quotes
book
Create a confirmed service reservation
pay
Authorise and capture payment (or set up escrow)
cancel
Cancel a booking and trigger the refund flow
refund
Initiate or release an escrowed payment
dispute
Open a human-reviewed dispute via GeraWitness
verify-completion
Confirm service delivery and release escrow
audit
Retrieve signed audit trail for any transaction

Message Types

Name	Direction	Description
ActionRequest	agent→service	Signed payload carrying intent, constraints, and agent identity
ActionResponse	service→agent	Outcome, reference ID, and next allowed states
QuoteOffer	service→agent	Binding price quote valid for a TTL window
ConsentGate	service→agent	Human-in-the-loop prompt when spend exceeds per-user threshold
AuditRecord	bidirectional	Cryptographically signed event log entry

Transaction Lifecycle

1
discover
Agent queries service capabilities
2
negotiate
Agent sends constraints; service returns QuoteOffer
3
booked
Agent accepts quote; reservation created
4
payment-authorised
Payment authorised; funds in escrow
5
in-progress
Service delivery underway
6
pending-completion
Service claims completion; awaiting agent/user verify
7
complete
Delivery verified; escrow released
8
cancelled
Terminal: booking cancelled; refund initiated
9
disputed
Terminal pending: GeraWitness human review

Error Codes

Code	HTTP Status	Description
NEXUS_001	400	Malformed ActionRequest payload
NEXUS_002	401	Invalid or expired agent signature
NEXUS_003	402	Payment authorisation failed
NEXUS_004	404	Service or booking not found
NEXUS_005	409	State transition not allowed
NEXUS_006	422	Constraints incompatible with availability
NEXUS_007	429	Agent rate limit exceeded
NEXUS_008	503	Downstream service unavailable

Settlement Layer

Pluggable — reference implementation uses GeraCash + Stripe (authorise / capture / refund). Any PSP that supports those three semantics can be integrated.

Service Discovery

Services publish capabilities at /.well-known/gera-nexus.json — agent-readable JSON-LD.

Human-in-the-Loop

ConsentGate messages route to GeraWitness for out-of-band human approval when per-user spend limits are exceeded or disputes are filed.

What's New

v0.1.02026-05-01
Initial draft spec. Core capabilities: discover, negotiate, book, pay, cancel, refund, dispute, verify-completion, audit.