io.github.omoshola-o/xap

XAP SDK

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.

Install

pip install xap-sdk

For MCP integration (Claude, Cursor, any MCP-compatible AI):

pip install xap-sdk[mcp]

Quickstart: Two Agents, One Settlement, Full Provenance

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())

The Verification Handshake

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 None

No other agent protocol has Step 2. Verification against real Verity receipts before a single dollar is committed.

Three-Agent Split Settlement

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())

What XAP Does

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

The Six Primitives

The Stack

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.

MCP Integration

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 Desktop

Run manually:

xap-mcp

The 8 MCP tools:

Full MCP docs →

Examples

Institutional Verification

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}")

Causal Chain Verification

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']}")

Key Concepts

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.

Links

• XAP Protocol Specification
• Verity Truth Engine
• Agentra Rail — Production Infrastructure
• Discord Community

Citation

@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}
}

License

MIT