io.github.omoshola-o/xap

Official

by agentra-commerce · Python

Agent settlement protocol — discover, negotiate, settle, and verify with XAP.

Protocol for AI agents to discover, negotiate, and settle agreements with verification.

Topics

agent-commerceai-agentsautonomous-agentsclaudecursorescrowmcpopen-sourcepython-sdksettlementverityxap-protocol

README.md12 KBView on GitHub

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

bash

pip install xap-sdk

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

bash

pip install xap-sdk[mcp]

Quickstart: Two Agents, One Settlement, Full Provenance

python

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:

python

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

python

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

#	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.

The Stack

code

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

json

{
  "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:

bash

pip install xap-sdk[mcp]
python -m xap.mcp.setup   # auto-configure Claude Desktop

Run manually:

bash

xap-mcp

The 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

Full MCP docs →

Examples

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.

Institutional Verification

For systems that need audit-grade verification, the SDK provides full verification of all seven trust properties:

python

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:

python

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.

Citation

bibtex

@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

Install

Configuration

Environment variables

XAP_MODE

Operating mode: 'sandbox' (free, no key needed) or 'live' (requires API key)

XAP_API_KEYsecret

API key for live mode (not needed for sandbox)

claude_desktop_config.json

{
  "mcpServers": {
    "xap": {
      "command": "npx",
      "args": [
        "-y",
        "@agenticamem/xap-mcp@0.4.2"
      ],
      "env": {
        "XAP_MODE": "<YOUR_XAP_MODE>",
        "XAP_API_KEY": "<YOUR_XAP_API_KEY>"
      }
    }
  }
}

Topics

XAP SDK

Install

Quickstart: Two Agents, One Settlement, Full Provenance

The Verification Handshake

Three-Agent Split Settlement

What XAP Does

The Six Primitives

The Stack

MCP Integration

Examples

Institutional Verification

Causal Chain Verification

Key Concepts

Links

Citation

License

Install

Configuration