0.2.0

AgentEscrow402 SDK

Python SDK, LangChain Tool, and MCP Server for trustless AI agent escrow payments on Casper Network.

---

Overview

This directory contains three integration layers for AgentEscrow402:

---

2-minute quickstart

For judges and first-time developers. Zero config, zero secrets, works against the live sandbox.

# 1. clone + install (30s)
git clone https://github.com/alexbelij/AgentEscrow402.git
cd AgentEscrow402
pip install httpx cryptography pydantic

# 2. run the quickstart (60s)
python examples/quickstart.py --api-url https://agentescrow402-api-ywm8.onrender.com

Expected output (real testnet, one create + one release):

connected: {'status': 'ok', ...}
buyer identity: <64-hex>
escrow created: <service_hash> status=created
escrow released: status=released deploy_hash=<hex>

That's it. The deploy_hash links to cspr.live if you want to inspect the on-chain state yourself.

What just happened

1. EscrowClient.generate() produced a fresh Ed25519 identity (no wallet setup, no funded testnet account required for the sandbox flow).
2. create_escrow produced a signed request; the server locked funds and returned a service_hash you can reference later.
3. release produced another signed request; the server released the funds and returned a deploy_hash.

For the full autonomous buyer/seller/arbiter loop (with a real dispute and an LLM arbitration call), run:

python examples/escrow_agent.py --api-url https://agentescrow402-api-ywm8.onrender.com

Next steps

• LangChain: drop EscrowPaymentTool into any agent — see sdk/langchain_tool.py.
• MCP: expose 26 escrow tools to Claude / GPT / any MCP client — see sdk/mcp_server.py.
• Judging: docs/HOW_TO_JUDGE.md maps the 8 criteria to concrete files and endpoints.

---

Quick Start

Install

pip install httpx cryptography pydantic
# For MCP server:
pip install mcp
# For LangChain:
pip install langchain

Python SDK — 3 lines to create an escrow

from sdk.client import EscrowClient

async with EscrowClient.generate("https://agentescrow402-api-ywm8.onrender.com") as client:
    escrow = await client.create_escrow(
        receiver="ab" * 32,  # receiver's 64-hex Casper account hash
        amount=5000,
        ttl=300
    )
    print(f"Escrow created: {escrow['service_hash']}")
    
    # Release funds after work is delivered
    await client.release(escrow["service_hash"], amount=5000)

LangChain — drop-in tool

from sdk.langchain_tool import EscrowPaymentTool

tool = EscrowPaymentTool("https://agentescrow402-api-ywm8.onrender.com", sender="agent-001")

result = await tool.run("create", receiver="ab" * 32, amount=5000)
result = await tool.run("release", service_hash=result["service_hash"])
result = await tool.run("reputation", agent="agent-001")

Supported actions: create, release, refund, dispute, status, reputation, batch_release, batch_cancel, claim_stream, risk

MCP Server — any LLM manages escrows

# stdio (default — for Claude Desktop, Cursor, etc.)
python -m sdk.mcp_server

# SSE (for remote/web connections)
pip install mcp[sse] uvicorn starlette
python -m sdk.mcp_server --transport sse --port 8402

---

Authentication

Signed mode (production)

The live API verifies Ed25519-signed X-Payment headers on every request. EscrowClient.generate() handles this automatically:

from sdk.client import EscrowClient

# Auto-generates a keypair and signs all requests
async with EscrowClient.generate("https://agentescrow402-api-ywm8.onrender.com") as client:
    print(client.sender)  # your 64-hex Ed25519 public key

To reuse the same identity across runs:

from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey

key = Ed25519PrivateKey.generate()  # persist this for reuse
client = EscrowClient("https://agentescrow402-api-ywm8.onrender.com", private_key=key)

Sandbox mode (local development)

async with EscrowClient("http://localhost:8000", sender="agent-001", sandbox=True) as client:
    escrow = await client.create_escrow(receiver="ab" * 32, amount=5000, ttl=300)

---

SDK Client Methods

---

MCP Tools (26)

---

x402 Payment Header

The x402 protocol header format used by the live API:

x402-v1;<escrow_hash>;<amount>;<sender>;<timestamp>;<nonce>;<signature>

Where signature = Ed25519.sign(key, "x402-v1;<escrow_hash>;<amount>;<sender>;<timestamp>;<nonce>;<METHOD>;<path>"), binding it to the exact HTTP method and path.

---

Examples

• examples/quickstart.py — minimal signed create → release
• examples/escrow_agent.py — full autonomous buyer/seller lifecycle with dispute and AI arbitration

---

Documentation

---

Live Resources

• Console: ae402.xyz/console
• API: agentescrow402-api-ywm8.onrender.com
• Sandbox: ae402.xyz/console/sandbox
• Contracts on CSPR.live: testnet.cspr.live/contract/612cead2...