XRPL Agent Wallet MCP

Secure, policy-controlled wallet infrastructure for AI agents operating on the XRP Ledger.

This MCP (Model Context Protocol) server enables AI agents to autonomously manage XRPL wallets and sign transactions within configurable policy boundaries. It implements a tiered security model where low-risk operations execute immediately while high-value transactions require human oversight.

Project Status: ✅ Phase 1 Implementation Complete - All core modules implemented and tested (222 tests passing) Security Status: ✅ Security Review Complete - 19 issues identified and remediated (see ADR-011) Integration Status: ✅ Escrow MCP Integration - Timing-aware parameters and escrow tracking (see ADR-012)

The Problem

AI agents need to transact on XRPL, but current approaches are insecure:

• Raw seeds stored in environment variables
• No policy enforcement on agent-initiated transactions
• No human oversight for high-value operations
• No audit trail for compliance

The Solution

A security-first MCP server that provides:

• Encrypted key storage - Keys never exposed in plaintext
• Policy engine - Declarative rules control what agents can do
• Tiered approval - Human oversight scales with transaction risk
• Full audit trail - Tamper-evident logging for compliance

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                     XRPL Agent Wallet MCP Server                     │
├─────────────────────────────────────────────────────────────────────┤
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  │
│  │ Input Validation │  │  Policy Engine   │  │ Signing Service  │  │
│  │   (Zod schemas)  │─▶│  (Tier routing)  │─▶│  (AES-256-GCM)   │  │
│  └──────────────────┘  └──────────────────┘  └──────────────────┘  │
│                              │                        │             │
│                              ▼                        ▼             │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  │
│  │   Rate Limiter   │  │  Audit Logger    │  │   XRPL Client    │  │
│  │  (Token bucket)  │  │  (Hash chains)   │  │    (xrpl.js)     │  │
│  └──────────────────┘  └──────────────────┘  └──────────────────┘  │
├─────────────────────────────────────────────────────────────────────┤
│                         11 MCP Tools                                 │
│  wallet_create │ wallet_sign │ wallet_balance │ wallet_policy_check │
│  wallet_rotate │ wallet_list │ wallet_history │ wallet_fund         │
│  policy_set    │ tx_submit   │ tx_decode                            │
└─────────────────────────────────────────────────────────────────────┘

Key Features

Security-First Design

Tiered Approval Model

Companion to xrpl-escrow-mcp

This wallet MCP is designed as the signing layer for xrpl-escrow-mcp:

xrpl-escrow-mcp              xrpl-wallet-mcp              XRPL Network
(builds unsigned TX)    →    (signs with policy)     →    (validates)

But it's not limited to escrow - it supports all 32 XRPL transaction types.

Quick Start

1. Install

npm install -g xrpl-agent-wallet-mcp

2. Configure Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "xrpl-wallet": {
      "command": "xrpl-agent-wallet-mcp",
      "env": {
        "XRPL_NETWORK": "testnet",
        "XRPL_WALLET_PASSWORD": "your-secure-password"
      }
    }
  }
}

3. Create Your First Wallet

Ask Claude: "Create a new XRPL wallet on testnet for my AI agent"

MCP Tools

Configuration

Environment Variables

Policy Configuration

Policies are JSON files controlling agent behavior:

{
  "version": "1.0.0",
  "name": "conservative",
  "network": "testnet",
  "tiers": {
    "autonomous": { "max_amount_drops": "100000000" },
    "delayed": { "max_amount_drops": "1000000000", "delay_seconds": 300 },
    "cosign": { "quorum": 2 }
  },
  "limits": {
    "daily_volume_drops": "1000000000",
    "max_tx_per_hour": 10
  },
  "destinations": {
    "mode": "allowlist",
    "addresses": ["rKnownExchange...", "rTrustedPartner..."]
  },
  "blocklist": {
    "addresses": [],
    "memo_patterns": ["ignore previous", "system prompt"]
  }
}

Security Model

XRPL Native Security

• Regular Keys: Agent signs with rotatable key; master key stays cold
• Multi-Sign: Tier 3 transactions require human co-signature (2-of-N)
• Network Isolation: Separate keystores per network prevent accidents

Key Protection

User Password
     │
     ▼ Argon2id (64MB, 3 iterations)
Master Key
     │
     ▼ AES-256-GCM
Encrypted Wallet Keys
     │
     ▼ File (0600 permissions)
~/.xrpl-wallet-mcp/{network}/wallets/

Prompt Injection Defense

The policy engine includes defenses against prompt injection:

• Memo field pattern matching blocks common attack vectors
• Policy rules are immutable at runtime (agent cannot self-modify)
• Context field sanitized before audit logging

Escrow Integration (v0.2.0)

Enhanced support for working with xrpl-escrow-mcp and other MCP servers:

Important: Testnet/devnet faucets now provide ~100 XRP (previously 1000 XRP). Use initial_balance_drops from wallet_fund response instead of hardcoding amounts.

See Network Timing Reference for detailed timing considerations.

Sequence Race Condition Fix (v0.2.1)

Resolved tefPAST_SEQ errors in rapid multi-transaction workflows (escrow create → finish):

Key principle: Never rely solely on ledger queries for sequence after submitting a transaction. The ledger may return stale data before the ledger closes (~3-5 seconds on testnet).

See ADR-013: Sequence Autofill for technical details.

Security Hardening (v0.1.1)

Following a comprehensive security review, the following hardening measures were implemented:

See ADR-011 for complete details.

Documentation

Architecture (Arc42)

• Introduction - Goals, stakeholders, scope
• Constraints - Technical and regulatory
• Context - System boundaries (C4 Level 1)
• Solution Strategy - Key decisions
• Building Blocks - Components (C4 Level 2/3)
• Runtime View - Sequence diagrams
• Deployment - Infrastructure
• Crosscutting - Security, logging, errors
• ADRs - 13 architecture decisions

Security

• Threat Model - STRIDE analysis, 20 threats
• Security Requirements - 52 requirements
• Compliance Mapping - SOC 2, MiCA
• OWASP LLM Mitigations - Top 10 coverage

API Reference

• Tool Specifications - All 11 MCP tools
• Policy Schema - Complete policy format
• Network Configuration - Network setup

User Guides (Diataxis)

• Tutorials: Getting Started, Escrow Workflow
• How-To: Configure Policies, Rotate Keys, Network Config
• Reference: API, Transaction Types, Network Timing
• Explanation: Security Model, Policy Engine

Development

Prerequisites

• Node.js 22+
• npm 10+

Setup

git clone https://github.com/9RESE/xrpl-agent-wallet-mcp.git
cd xrpl-agent-wallet-mcp
npm install
npm run build

Testing

npm test                    # Watch mode
npm run test:run           # Single run
npm run test:coverage      # Coverage report (90% target)
npm run test:security      # Security tests

Test Coverage Requirements

Roadmap

Contributing

See CONTRIBUTING.md for guidelines.

Security vulnerabilities: See SECURITY.md - do NOT open public issues.

License

MIT License - see LICENSE

Acknowledgments

Project Maintainers

This project is created and maintained by 9 RESE' LLC.

Community Support

Special thanks to the $POSSE XRPL community project for their support in initiating and maintaining this open source wallet infrastructure for AI agents on the XRP Ledger.

Built With

• XRPL Foundation - XRP Ledger and xrpl.js
• Anthropic - Model Context Protocol
• xrpl-escrow-mcp - Companion project
• Security research from AWS Nitro, OWASP, and the agent wallet community

Contact

• General Inquiries: contact@9rese.com
• Security Issues: See SECURITY.md - do NOT open public issues
• Bug Reports: Open an issue
• Discussions: Start a discussion