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

Layer	Protection
Transport	TLS 1.3 for XRPL connections
Input	Zod schema validation, injection detection
Authentication	Argon2id (64MB), progressive lockout
Authorization	Tool sensitivity levels, rate limiting
Policy	Immutable rules engine, tier classification
Cryptographic	AES-256-GCM, SecureBuffer memory handling
XRPL Native	Regular Keys, Multi-Sign, network isolation
Audit	HMAC-SHA256 hash-chained logs

Tiered Approval Model

Tier	Criteria	Agent Action	Human Action
Autonomous	< 100 XRP, known destination	Sign immediately	None
Delayed	100-1000 XRP	Sign after 5-min delay	Can veto
Co-Sign	> 1000 XRP, new destination	Request approval	Must approve
Prohibited	Policy violation, blocklist	Reject	N/A

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

Tool	Purpose	Sensitivity
wallet_create	Create new wallet with policy	HIGH
wallet_sign	Sign transaction (policy-controlled)	CRITICAL
wallet_balance	Query balance and reserves	LOW
wallet_policy_check	Dry-run policy evaluation	LOW
wallet_rotate	Rotate regular key	DESTRUCTIVE
wallet_list	List managed wallets	LOW
wallet_history	Query transaction history	LOW
wallet_fund	Fund wallet from testnet/devnet faucet	HIGH
policy_set	Update policy configuration	CRITICAL
tx_submit	Submit signed transaction	HIGH
tx_decode	Decode transaction blob	LOW

Configuration

Environment Variables

Variable	Required	Default	Description
XRPL_NETWORK	Yes	-	mainnet, testnet, or devnet
XRPL_WALLET_PASSWORD	Yes	-	Master encryption password
XRPL_WALLET_KEYSTORE_PATH	No	~/.xrpl-wallet-mcp	Keystore location
XRPL_WALLET_POLICY	No	Built-in	Path to policy JSON
LOG_LEVEL	No	info	debug, info, warn, error

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:

Enhancement	Tool	Description
Timing-Aware Funding	wallet_fund	wait_for_confirmation parameter with retry logic (15 attempts, 2s intervals)
Balance Propagation	wallet_balance	wait_after_tx parameter (0-30000ms) ensures accurate balance after transactions
Escrow Tracking	tx_submit	Returns tx_type, sequence_used, and escrow_reference for complete escrow lifecycle
Ledger Consistency	All tools	ledger_index in responses enables consistency verification

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

Component	Fix	Description
SequenceTracker	New class	Tracks signed sequences per address with 60-second TTL
wallet_sign	auto_sequence	Uses MAX(ledger_sequence, last_signed + 1) to prevent stale sequences
tx_submit	next_sequence	Returns next sequence to use, tracks after successful submission
Debug Logging	Built-in	Sequence calculations logged for troubleshooting

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:

Area	Improvement
Environment	Required XRPL_WALLET_PASSWORD - fail-fast on missing config
Key Storage	Consistent seed format (UTF-8) prevents cryptographic failures
Multi-Sign	Cryptographic signature verification using ripple-keypairs
Audit Logs	Fixed hash chain integrity for tamper detection
Key Rotation	Regular keys now persisted and preferred over master key
Rate Limiting	Lockout state persists across server restarts
ReDoS	Pattern analysis prevents regex denial-of-service
Production	Stack traces and logs sanitized for production deployment

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

Module	Target
src/keystore/	95%
src/policy/	95%
src/signing/	95%
src/validators/	95%
Overall	90%

Roadmap

Phase	Scope	Status
1 (MVP)	Local keystore, policy engine, 11 MCP tools	✅ Complete
2	Cloud KMS (AWS/GCP), HSM integration	Planned
3	TEE deployment (AWS Nitro), KYA identity	Future

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