Universal Monero x402 Facilitator (Daemon)

An open-source, privacy-respecting payment oracle that implements the x402 (Payment Required) protocol for Monero (XMR).

This project acts as a sidecar daemon for web servers, AI agents, and microservices. It bridges the gap between the "Agentic Web" and Monero's private-by-default network, allowing any application (Go, JS, Python) to accept XMR using the Coinbase x402 standard.

Vision

To provide a sovereign, self-hosted alternative to corporate payment facilitators. By running this daemon alongside your application, you can gate resources behind XMR micro-payments while maintaining 100% control over your own View Keys and Node infrastructure.

Protocol Flow

1. Merchant App calls /invoices to generate a subaddress and price.
2. Merchant App returns a 402 Payment Required header to the Client.
3. Client pays via XMR and retrieves the tx_key from their wallet.
4. Client submits tx_id and tx_key to the Merchant.
5. Merchant App calls /settle on this Facilitator to verify the payment proof and enforce the configured confirmation policy before unlocking the resource.

Features

• x402 Compliant: Implements /supported, /verify, and /settle endpoints.
• Privacy Centric: Generates unique subaddresses for every request; no address reuse.
• Universal Sidecar: RESTful API for creating invoices and verifying payments from any programming language.
• Cryptographic Proof-of-Payment: Uses Monero's tx_key (Transaction Secret Key) to verify sender ownership, preventing header spoofing and replay attacks.
• Persistent Storage: SQLite/SQLx backend tracks invoice lifecycles (Pending, Paid, Expired).
• Dynamic Market Pricing: Fetches real-time XMR/USD exchange rates via Kraken.
• Configurable Confirmation Policy: Supports both instant 0-conf verification and confirmation-gated settlement via environment configuration.
• Privacy Centric: Generates unique subaddresses for every request; no address reuse.

Tech Stack

• Language: Rust (Axum)
• Database: SQLite (SQLx)
• Crypto Integration: Monero-Wallet-RPC
• Pricing: Kraken and CryptoCompare (fallback) API

Developer Tooling

This project includes a standard OpenAPI 3.1 specification.

• openapi.yaml: Can be imported into Postman or used to generate client libraries in Go, TS, or Python.

Getting Started

Prerequisites

1. Monero Wallet RPC: Must be running with a wallet file loaded.

   monero-wallet-rpc --stagenet --rpc-bind-port 18083 --disable-rpc-login --wallet-file your_wallet
   

2. Rust Toolchain: (Cargo/Rustc)

Installation

1. Configure:

   cp .env.example .env
   # Edit .env with your RPC URL and Database path
   

2. Initialize Database:

   touch facilitator.db
   sqlite3 facilitator.db "CREATE TABLE invoices (address TEXT PRIMARY KEY, amount_required INTEGER NOT NULL, metadata TEXT, payer_id TEXT, status TEXT, tx_id TEXT, created_at INTEGER NOT NULL);"
   

3. Build & Run:

   cargo run
   

Environment Variables

Variable	Default	Description
DATABASE_URL	sqlite:facilitator.db	SQLite database location
MONERO_RPC_URL	http://127.0.0.1:18083/json_rpc	Monero Wallet RPC endpoint
HOST	0.0.0.0	Bind host
PORT	3113	Bind port
XMR_NETWORK	mainnet	Network identifier returned by /supported
CONFIRMATIONS_REQUIRED	0	Minimum confirmations required before verification succeeds
VERIFY_MAX_ATTEMPTS	300	Number of verification polling attempts
VERIFY_POLL_INTERVAL_SECS	30	Delay between verification polling attempts

Standard x402 API Reference

1. Supported Kinds (GET /supported)

Returns the network and scheme supported by this facilitator.

• Returns: {"kinds": [{"x402Version": 2, "scheme": "exact", "network": "monero:stagenet"}]}

2. Settle Payment (POST /settle)

The primary endpoint for unlocking resources.

• Input:

  {
    "paymentPayload": {
      "address": "7...",
      "tx_id": "...",
      "tx_key": "..."
    },
    "paymentRequirements": {
      "scheme": "exact",
      "network": "monero:stagenet"
    }
  }
  

• Returns: {"success": true, "transaction": "...", "network": "monero:stagenet", "payer": "anonymous"}

---

Merchant Helper API

Create Invoice (POST /invoices)

Used by your server to prepare a challenge for the user.

• Input: {"amount_usd": 0.10}
• Returns: {"address": "7...", "amount_piconero": 650000, "invoice_id": "...", "status": "pending"}

Security & Confirmation Levels

By default, this facilitator is configured for 0-Conf (Instant) verification, allowing resources to be unlocked as soon as a transaction is visible to the wallet RPC.

For applications requiring stronger settlement guarantees, the facilitator can enforce a minimum confirmation depth before a payment is considered valid.

Configuration

CONFIRMATIONS_REQUIRED=0
VERIFY_MAX_ATTEMPTS=15
VERIFY_POLL_INTERVAL_SECS=2

Confirmation Policy

• CONFIRMATIONS_REQUIRED=0

  • Instant verification.
  • Suitable for low-value digital goods, API requests, AI agent actions, and metered services.

• CONFIRMATIONS_REQUIRED=1

  • Requires inclusion in a block.
  • Provides protection against mempool-level race conditions.

• CONFIRMATIONS_REQUIRED=2+

  • Requires additional confirmation depth before verification succeeds.
  • Recommended for higher-value resources where stronger settlement assurance is desired.

Verification Behavior

When a confirmation requirement is configured, the facilitator will poll the Monero Wallet RPC until either:

1. The transaction has reached the required confirmation depth.
2. The configured verification retry limit is exceeded.

If the transaction amount is sufficient but the confirmation threshold has not yet been reached, verification will return:

{
  "isValid": false,
  "invalidReason": "Insufficient confirmations"
}

Applications can retry verification later or increase the polling window through the environment configuration.

The tx_key Proof

Because Monero is private, a transaction hash (tx_id) is not enough to prove ownership. This daemon requires the tx_key (Transaction Secret Key) from the client. The daemon uses this to verify:

1. The transaction actually sent the expected amount.
2. The transaction was sent to the correct one-time subaddress.
3. The sender actually possesses the secret key for that transaction.

Security: The tx_key Advantage

Unlike transparent ledgers where seeing a transaction is enough proof, Monero's privacy requires the sender to prove they are the one who sent the funds. This facilitator requires the client to provide the tx_key generated by their wallet.

• The facilitator uses check_tx_key via RPC to verify that the key proves a transfer to the specific subaddress.
• This ensures that users cannot "spoof" headers by simply finding high-value TXIDs on a block explorer.

Status: Proof of Concept

• Universal REST API
• Cryptographic verification (tx_key)
• SQLite persistence
• Configurable confirmation enforcement
• Webhook support (Next)
• Tor / .onion service support (Next)

Contributing

This is an open-source project designed to strengthen the Monero ecosystem. Contributions, bug reports, and integration examples are welcome.