xrpl-escrow-mcp

Open-source MCP (Model Context Protocol) server for trustless escrow operations on the XRP Ledger.

Features

• Non-Custodial: Funds held in XRPL escrow objects, never by the server
• Crypto-Conditions: PREIMAGE-SHA-256 for trustless fulfillment
• Multi-Network: Mainnet, Testnet, Devnet support
• AI-Native: Designed for AI agent commerce
• Credential Verification: XRPL Credentials (XLS-70) for agent identity
• Wallet Integration: Escrow index calculation for seamless wallet MCP integration

Recent Improvements (v0.1.x)

Feature	Description
Escrow Index Calculation	Deterministic ledger entry index using XRPL keylet pattern
Ledger Time Accuracy	Uses authoritative ledger close time for status determination
Enhanced Responses	All tools return escrow_index, ledger_index, fee estimates
Time Validation	Validates cancel_after > finish_after constraint
Fee Estimation	Conditional escrow finish fee calculation
Human-Readable Timing	Status includes timing descriptions ("in 5 days", "2 hours ago")

See ADR-007 for details.

Quick Start

Using npx (Recommended)

npx @xrpl-escrow/mcp-server

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "xrpl-escrow": {
      "command": "npx",
      "args": ["@xrpl-escrow/mcp-server"],
      "env": {
        "XRPL_NETWORK": "testnet"
      }
    }
  }
}

Claude Code Configuration

Add to your project's .claude/settings.json:

{
  "mcpServers": {
    "xrpl-escrow": {
      "command": "npx",
      "args": ["@xrpl-escrow/mcp-server"],
      "env": {
        "XRPL_NETWORK": "testnet"
      }
    }
  }
}

Available Tools

Tool	Description
escrow_create	Create an unsigned EscrowCreate transaction
escrow_finish	Create an unsigned EscrowFinish transaction (supports credential verification)
escrow_cancel	Create an unsigned EscrowCancel transaction
escrow_status	Query escrow status on-chain
generate_condition	Generate PREIMAGE-SHA-256 condition/fulfillment pair
list_escrows	List escrows for an address
oracle_verify	[EXPERIMENTAL] Request verification (requires AgentEscrow service)
verify_agent_credential	Verify XRPL credentials for an address (XLS-70)
list_agent_credentials	List all credentials held by an address

Example Usage

Create an Escrow

Create an escrow for 10 XRP from rSenderAddress to rRecipientAddress
with a 24-hour expiration

The MCP server will:

1. Generate a crypto-condition (if needed)
2. Return an unsigned EscrowCreate transaction
3. You sign and submit via your wallet

Check Escrow Status

What's the status of the escrow at sequence 12345 for owner rSenderAddress?

Finish an Escrow

Finish the escrow at sequence 12345 for owner rSenderAddress
using fulfillment ABC123...

Verify Agent Credentials (XLS-70)

Verify credentials for rAgentAddress

Check if rAgentAddress has "EscrowAgent" credential from rIssuerAddress

Finish with Credential Verification

Finish escrow at sequence 12345 for owner rSenderAddress
and verify the finisher has "EscrowAgent" credential from rIssuerAddress

The server verifies credentials on-chain before building the transaction.

Configuration

Environment Variables

Variable	Default	Description
XRPL_NETWORK	mainnet	Network: mainnet, testnet, devnet
XRPL_SERVER	-	Custom XRPL WebSocket URL
AGENT_ESCROW_API_URL	-	AgentEscrow service URL (for oracle features)
AGENT_ESCROW_API_KEY	-	AgentEscrow API key

HTTP Transport (Optional)

For standalone or containerized deployments, use HTTP transport instead of STDIO:

Variable	Default	Description
MCP_TRANSPORT	stdio	Transport: stdio or http
MCP_HTTP_PORT	3000	HTTP server port
MCP_HTTP_HOST	127.0.0.1	HTTP server bind address

Rate Limiting (HTTP Transport)

When using HTTP transport, rate limiting protects against abuse:

Variable	Default	Description
RATE_LIMIT_WINDOW_MS	60000	Time window in milliseconds
RATE_LIMIT_MAX_REQUESTS	100	Max requests per window
RATE_LIMIT_SKIP_FAILED	false	Exclude failed requests from count
RATE_LIMIT_SKIP_SUCCESS	false	Exclude successful requests from count

Example: HTTP deployment with custom rate limits

MCP_TRANSPORT=http \
MCP_HTTP_PORT=8080 \
RATE_LIMIT_MAX_REQUESTS=50 \
npx @xrpl-escrow/mcp-server

Networks

Network	WebSocket URL
Mainnet	wss://xrplcluster.com
Testnet	wss://s.altnet.rippletest.net:51233
Devnet	wss://s.devnet.rippletest.net:51233

Security

This MCP server is non-custodial by design:

• Never has access to private keys
• Returns unsigned transaction blobs for client-side signing
• All escrow states verifiable directly on XRPL
• Strict input validation on all parameters

Security Hardening (v0.1.x)

The server implements multiple security layers for agent-to-agent commerce:

Feature	Description
Input Bounds	Hex strings limited to 1024 chars (DoS prevention)
Secrets Separation	API keys isolated from loggable config
Sensitive Field Markers	_sensitive: true flags on fulfillment/preimage
Error Sanitization	No stack traces, paths, or credentials in errors
Fulfillment Pre-Validation	Catches mismatches before network fees
Memo Warnings	Clear warnings about permanent public storage
BigInt Amounts	Safe handling of large XRP amounts (>2^53 drops)
Rate Limiting	DoS protection for HTTP transport
Dependency Updates	MCP SDK 1.25.3, minimal dependencies

See Security Audit, ADR-003, and ADR-004 for details.

Development

# Clone the repository
git clone https://github.com/agentescrow/xrpl-escrow-mcp
cd xrpl-escrow-mcp

# Install dependencies
pnpm install

# Build
pnpm build

# Run unit tests
pnpm test

# Run unit tests with coverage
pnpm test:coverage

# Run E2E tests (against XRPL Testnet)
pnpm test:e2e

# Development mode (watch)
pnpm dev

Test Suite

Type	Tests	Description
Unit	308	Fast tests with mocked XRPL responses
Security	65	Secrets management, error sanitization
Credentials	121	Credential types, utils, verification
E2E	14	Real transactions on XRPL Testnet
Total	443	Full test coverage

E2E tests validate the complete escrow lifecycle against XRPL Testnet:

• Time-based and conditional escrows
• Crypto-condition generation and fulfillment
• Error handling (timing violations, insufficient funds, etc.)

Unit Test Coverage

Metric	Coverage
Statements	97.67%
Branches	89.63%
Functions	100%
Lines	97.67%

Related Projects

• xrpl.js: Official XRPL JavaScript/TypeScript library
• five-bells-condition: Crypto-conditions library

Documentation

For AI Agents

• AGENTS.md - Compact reference for AI agents (tool examples, workflows, error handling)

Quick Start

• Getting Started - Set up and run your first escrow
• Tools Reference - Complete API reference

User Guides (Diataxis)

• Tutorial: First Escrow - Step-by-step guide
• Explanation: Escrow Lifecycle - Concepts

How-To Guides

• Agent Integration - AI agent workflows and patterns
• Verify Credentials - XRPL credential verification (XLS-70)
• Wallet Signing - XUMM, xrpl.js, Ledger signing
• Use Case Recipes - E-commerce, freelance, swaps
• Troubleshooting - Common issues and solutions
• Run Tests - Unit and E2E testing

Architecture (Arc42 + C4)

• Architecture Overview - System design
• ADR-001: Non-Custodial Design
• ADR-002: E2E Testing Strategy
• ADR-003: Security Hardening
• ADR-004: Security Improvements - SDK update, BigInt, rate limiting
• ADR-005: Credential Integration - XRPL Credentials (XLS-70)
• ADR-006: Type Safety Improvements - XRPL typed interfaces, code quality
• ADR-007: Escrow Timing & Index - Escrow index calculation, ledger time
• C4 Context Diagram - System context

Security

• Security Audit - Comprehensive security analysis
• Security Fixes Plan - Implementation details
• Code Review Report - Deep code review with findings

Technical

• Full Specification - Detailed MCP specification

Contributing

Contributions are welcome! Please read our Contributing Guide before submitting a PR.

License

MIT License - see LICENSE for details.

Acknowledgments

This project is created and maintained by 9 RESE' LLC as part of the $POSSE initiative on the XRP Ledger.

Special thanks to:

• The XRPL Foundation for the XRP Ledger infrastructure
• Anthropic for the Model Context Protocol specification
• The XRPL developer community

---

Built with the Model Context Protocol for the XRP Ledger ecosystem.