Settlement objects for autonomous agent commerce.
XAP is the only protocol combining schema validation, cryptographic signatures, enforced state machines, idempotency, governed receipts, and replayable reasoning into one governed object model.
pip install xap-sdkFor MCP integration (Claude, Cursor, any MCP-compatible AI):
pip install xap-sdk[mcp]import asyncio
from xap import XAPClient
# Create two agents — sandbox uses fake money, no external services needed
provider = XAPClient.sandbox(balance=0)
consumer = XAPClient.sandbox(balance=100_000) # $1,000.00
consumer.adapter.fund_agent(str(provider.agent_id), 0)
provider.adapter = consumer.adapter
# Provider registers a capability with SLA guarantees
provider_identity = provider.identity(
display_name="SummarizeBot",
capabilities=[{
"name": "text_summarization",
"version": "1.0.0",
"pricing": {"model": "fixed", "amount_minor_units": 500, "currency": "USD", "per": "request"},
"sla": {"max_latency_ms": 2000, "availability_bps": 9950},
}],
)
consumer.discovery.register(provider_identity)
# Consumer discovers and negotiates
results = consumer.discovery.search(capability="text_summarization")
offer = consumer.negotiation.create_offer(
responder=provider.agent_id,
capability="text_summarization",
amount_minor_units=500,
)
accepted = provider.negotiation.accept(offer)
# Settle with full decision provenance
async def settle():
settlement = consumer.settlement.create_from_contract(
accepted_contract=accepted,
payees=[{"agent_id": str(provider.agent_id), "share_bps": 10000}],
)
locked = await consumer.settlement.lock(settlement)
result = await consumer.settlement.verify_and_settle(
settlement=locked,
condition_results=[{
"condition_id": "cond_0001",
"type": "deterministic",
"check": "output_delivered",
"passed": True,
}],
)
# Every decision is deterministically replayable
assert consumer.receipts.verify_replay(result.verity_receipt)
print(f"Settlement: {result.receipt['outcome']}")
print(f"Replay verified: {result.verity_receipt['replay_hash']}")
return result
asyncio.run(settle())What separates XAP from every other agent protocol is Step 2 — trust verified before money moves:
from xap import XAPClient
from xap.verify import verify_manifest
async def find_trusted_agent(capability: str, min_success_rate_bps: int = 9000):
client = XAPClient.sandbox()
# Step 1 — DECLARE: query the registry
results = client.discovery.search(
capability=capability,
min_success_rate_bps=min_success_rate_bps,
include_manifest=True,
)
for agent in results:
# Step 2 — VERIFY: replay Verity receipts to confirm claimed track record
manifest = agent["manifest"]
verification = await verify_manifest(
manifest=manifest,
sample_receipts=3,
)
if verification.confirmed:
print(f"Agent {agent['agent_id']} verified:")
print(f" Claimed: {manifest['capabilities'][0]['attestation']['success_rate_bps'] / 100}%")
print(f" Verified: {verification.verified_rate_bps / 100}%")
print(f" Receipts replayed: {verification.receipts_checked}")
# Step 3 — NEGOTIATE: enter negotiation with verified trust
return client.negotiation.create_offer(
responder=agent["agent_id"],
capability=capability,
amount_minor_units=1000,
)
return NoneNo other agent protocol has Step 2. Verification against real Verity receipts before a single dollar is committed.
import asyncio
from xap import XAPClient
async def multi_agent_workflow():
orchestrator = XAPClient.sandbox(balance=500_000)
executor = XAPClient.sandbox(balance=0)
verifier = XAPClient.sandbox(balance=0)
executor.adapter = orchestrator.adapter
verifier.adapter = orchestrator.adapter
orchestrator.adapter.fund_agent(str(executor.agent_id), 0)
orchestrator.adapter.fund_agent(str(verifier.agent_id), 0)
settlement = orchestrator.settlement.create(
payer_id=str(orchestrator.agent_id),
payees=[
{"agent_id": str(executor.agent_id), "share_bps": 7000}, # 70%
{"agent_id": str(verifier.agent_id), "share_bps": 2000}, # 20%
{"agent_id": str(orchestrator.agent_id), "share_bps": 1000}, # 10%
],
amount_minor_units=10_000, # $100.00
currency="USD",
)
locked = await orchestrator.settlement.lock(settlement)
result = await orchestrator.settlement.verify_and_settle(
settlement=locked,
condition_results=[{
"condition_id": "cond_0001",
"type": "probabilistic",
"check": "quality_score",
"score_bps": 9200,
"threshold_bps": 8500,
"passed": True,
}],
)
print(f"Outcome: {result.receipt['outcome']}")
print(f"Executor: ${result.receipt['payouts'][str(executor.agent_id)] / 100:.2f}")
print(f"Verifier: ${result.receipt['payouts'][str(verifier.agent_id)] / 100:.2f}")
asyncio.run(multi_agent_workflow())Every agent-to-agent economic interaction produces governed objects that are:
- Schema-validated — structured, machine-readable, JSON Schema Draft 2020-12
- Cryptographically signed — Ed25519, tamper-evident
- State-transitioned — explicit state machines, no implicit jumps
- Idempotent — safe retries, no duplicate effects
- Receipted — every settlement emits a governed
ExecutionReceipt - Replayable — every decision captured in a
VerityReceipt, independently verifiable
| # | Primitive | What It Does |
|---|---|---|
| 0 | AgentManifest |
Signed, Verity-backed trust credential. How agents find and verify each other. |
| 1 | AgentIdentity |
Permanent economic passport with append-only reputation. |
| 2 | NegotiationContract |
Time-bound offer/counter/accept flow with conditional pricing. |
| 3 | SettlementIntent |
Conditional hold instruction with declared release conditions and split rules. |
| 4 | ExecutionReceipt |
Tamper-proof record of every economic event. |
| 5 | VerityReceipt |
Deterministically replayable proof of why a decision was made. |
xap-protocol — Open standard (MIT). The language agents speak.
verity-engine — Open source truth engine (Rust, MIT). The Git of financial truth.
xap-sdk — This package. Build XAP-native agents in Python.
Agentra Rail — Commercial infrastructure. Production settlement at scale.
Connect XAP to Claude, Cursor, Windsurf, or any MCP-compatible AI:
Quickest install (npm — no Python config needed):
{
"mcpServers": {
"xap": {
"command": "npx",
"args": ["-y", "@agenticamem/xap-mcp"]
}
}
}Add to your Claude Desktop config and restart. Works in sandbox mode with no account required.
Python install:
pip install xap-sdk[mcp]
python -m xap.mcp.setup # auto-configure Claude DesktopRun manually:
xap-mcpThe 8 MCP tools:
| Tool | What it does |
|---|---|
xap_discover_agents |
Search registry by capability, price, success rate |
xap_verify_manifest |
Verify agent trust credential via Verity receipt replay |
xap_create_offer |
Create a negotiation offer |
xap_respond_to_offer |
Accept, reject, or counter |
xap_settle |
Execute settlement with conditional hold |
xap_verify_receipt |
Verify any receipt (public, no auth) |
xap_check_balance |
Check sandbox or live balance |
xap_verify_workflow |
Verify complete causal chain of multi-agent workflow |
| Example | What It Shows |
|---|---|
two_agent_demo.py |
Full flow: discover, negotiate, settle, replay. The canonical starting point. |
three_agent_split.py |
Multi-party settlement with basis point splits. Atomic payment to multiple agents. |
unknown_outcome.py |
When verification is ambiguous. Partial settlement and refund scenarios. |
manifest_demo.py |
Build a manifest, sign it, verify receipts, query the registry. |
mcp_demo.py |
XAP as MCP tools. Negotiate and settle from a Claude conversation. |
For systems that need audit-grade verification, the SDK provides full verification of all seven trust properties:
from xap.verify import verify_receipt_full
# Verify a single receipt — checks all 7 properties
result = await verify_receipt_full("vrt_a1b2c3...")
print(f"TSA anchored: {result.tsa_anchored}")
print(f"Policy verified: {result.policy_verified}")
print(f"Signing key: {result.signing_key_id}")
print(f"Causal depth: {result.causal_depth}")For multi-agent workflows, verify the entire causal chain:
from xap.clients.workflow import WorkflowClient
wf = WorkflowClient(base_url="https://api.zexrail.com")
result = await wf.verify_workflow("wf_a1b2c3d4")
print(f"Chain length: {result['receipt_count']}")
print(f"All valid: {result['all_valid']}")Money is always integers. 500 means $5.00 (minor units). No floating point, ever. This is not a convention — it is an invariant enforced at every layer.
Shares are basis points. 4000 means 40%. All shares in a settlement must sum to exactly 10000. The settlement engine rejects anything else.
Every decision is replayable. The VerityReceipt captures inputs, rules, computation steps, and a replay hash. Any party can independently verify the outcome. Given the same inputs and rules, the same outcome is guaranteed.
Sandbox mode is zero-config. XAPClient.sandbox() gives you fake money, in-memory registry, and test adapter. No external services, no accounts, no configuration.
Manifests are credentials, not claims. An AgentManifest is signed with the agent's Ed25519 key and contains Verity receipt hashes from real past settlements. It is not "here is what I can do" — it is cryptographic proof of what has been done.
- XAP Protocol Specification
- Verity Truth Engine
- Agentra Rail — Production Infrastructure
- Discord Community
@software{xap_sdk_2026,
title = {XAP SDK: Settlement objects for autonomous agent commerce},
author = {Agentra Labs},
year = {2026},
doi = {10.5281/zenodo.18944370},
url = {https://github.com/agentra-commerce/xap-sdk}
}MIT