XAP Protocol
GitHub

XAP Conformance

What it means to be XAP-compatible — the seven required behaviors and how to test compliance

Seven Required Behaviors
Must Implement All
If your system does these seven things, it is XAP-compatible. Missing any one means the system is not conformant.
1

Produce valid objects

Every object validates against its JSON Schema (Draft 2020-12) before any effect occurs. Schema validation is the first gate.

All 6 primitives + RegistryQuery
2

Sign every object

Every XAP object is signed using Ed25519 with a key corresponding to a registered AgentIdentity. Unsigned objects are rejected.

Ed25519 signatures
3

Enforce state machines

NegotiationContract and SettlementIntent follow declared state transitions only. OFFER → COUNTER → ACCEPT or REJECT. No implicit jumps.

OFFER/COUNTER/ACCEPT/REJECT/EXPIRED
4

Handle idempotency

The same idempotency_key returns the existing result without creating duplicates. Retries are safe. No double settlements.

idempotency_key field
5

Issue receipts

Every settled SettlementIntent produces an ExecutionReceipt with adapter trace, payout details, and transaction references.

ExecutionReceipt
6

Capture decisions

Every significant decision produces a VerityReceipt with replay hash, policy snapshot, and evidence references. Deterministically replayable.

VerityReceipt
7

Serve a manifest

Every registered agent exposes a signed AgentManifest at /.well-known/xap.json with Verity-backed attestation data.

AgentManifest at /.well-known/xap.json
Optional Extensions
May Implement
Supported by some implementations but not required for conformance
  • Cross-currency FX support with locked rates
  • Multi-party splits beyond 2 participants
  • Webhook event delivery with HMAC signing
  • Real-time WebSocket event streaming
  • Custom settlement adapters (beyond Stripe and test)
  • Evidence WORM storage with object locking
  • Federation hints for cross-registry discovery (v1.1)
  • Composite scoring for RegistryQuery responses
Testing Compliance
Run the validation suite against your implementation
pip install xap-sdk
python -m xap.validate --endpoint https://your-system.com/api

# Individual checks:
python -m xap.validate --check schemas     # All 6 primitives
python -m xap.validate --check signatures  # Ed25519 signing
python -m xap.validate --check states      # State machine transitions
python -m xap.validate --check idempotency # Retry safety
python -m xap.validate --check receipts    # Receipt generation
python -m xap.validate --check verity      # Replay determinism
python -m xap.validate --check manifest    # /.well-known/xap.json

All seven checks must pass. The validation suite is open source and runs against any HTTP endpoint.

Looking to use a conformant implementation rather than build your own?

ZexRail — Reference Implementation