Python SDK

Full reference for the zexrail-sdk Python client library.

Installation

# Core SDK
pip install zexrail-sdk

# With MCP support
pip install zexrail-sdk[mcp]

# With LangChain integration
pip install zexrail-sdk[langchain]

# With all extras
pip install zexrail-sdk[all]

Requires Python 3.9 or later. Supports both sync and async usage.

ZexRailClient Initialization

Create a client instance to interact with the API.

from zexrail import ZexRailClient

# Production client
client = ZexRailClient(
    api_key="sk_live_your_key",
    base_url="https://api.zexrail.com/v1",  # default
    timeout=30,                                # seconds
    max_retries=3,
)

# Async client
from zexrail import AsyncZexRailClient

async_client = AsyncZexRailClient(api_key="sk_live_your_key")

Sandbox Mode

Use sandbox mode for development and testing. No real payments are processed.

from zexrail import ZexRailClient

client = ZexRailClient(
    api_key="sk_test_your_test_key",
    environment="sandbox",  # Uses sandbox API endpoint
)

# Sandbox provides:
# - Test agent identities
# - Simulated negotiations (instant accept/reject)
# - Mock settlement execution
# - Deterministic Verity hashes for testing

Method Reference

All available methods on the ZexRailClient.

Method	Arguments	Returns	Description
agents.register()	name, capabilities, endpoints	`AgentIdentity`	Register a new agent
agents.get()	agent_id	`AgentIdentity`	Retrieve agent by ID
agents.list()	status?, limit?	`List[AgentIdentity]`	List organization agents
agents.update()	agent_id, **fields	`AgentIdentity`	Update agent properties
agents.discover()	capabilities?, region?	`List[AgentIdentity]`	Discover agents in registry
negotiations.create()	initiator, responder, terms	`NegotiationContract`	Start a negotiation
negotiations.respond()	negotiation_id, action, terms?	`NegotiationContract`	Accept, reject, or counter
negotiations.get()	negotiation_id	`NegotiationContract`	Get negotiation details
settlements.create()	negotiation_id, adapter, splits?	`SettlementIntent`	Create settlement intent
settlements.execute()	settlement_id	`SettlementIntent`	Trigger execution
receipts.get()	receipt_id	`VerityReceipt`	Get receipt details
receipts.verify()	receipt_id	`VerificationResult`	Re-verify a receipt

Complete Example

End-to-end workflow: register, negotiate, settle, and verify.

from zexrail import ZexRailClient

client = ZexRailClient(api_key="sk_live_your_key")

# Register an agent
agent = client.agents.register(
    name="InvoiceBot",
    capabilities=["payment.process", "invoice.read"],
    endpoints={
        "webhook": "https://example.com/webhooks/xap",
        "healthCheck": "https://example.com/health",
    },
)

# Discover a counterparty
partners = client.agents.discover(capabilities=["logistics.track"])
partner = partners[0]

# Negotiate
negotiation = client.negotiations.create(
    initiator=agent.id,
    responder=partner.id,
    terms={"amount": {"value": 2500, "currency": "USD"}},
)

# Settle
settlement = client.settlements.create(
    negotiation_id=negotiation.id,
    adapter="stripe",
)

# Verify receipt
receipt = client.receipts.verify(settlement.receipt_id)
print(f"Verified: {receipt.status}")  # "valid"

Error Handling

from zexrail import ZexRailClient, XAPError, RateLimitError

client = ZexRailClient(api_key="sk_live_your_key")

try:
    agent = client.agents.get("agent-nonexistent")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except XAPError as e:
    print(f"Error {e.code}: {e.message}")
    # e.code      -> "not_found"
    # e.status    -> 404
    # e.message   -> "Agent not found"
    # e.request_id -> "req-abc123" (for support)