Solana Enterprise Payment Gateway

High-Throughput HTTP 402 Payment Channel Middleware

Language / runtime note. The Maven build targets Java 21 bytecode (<java.version>21</java.version>), the Spring Boot 3.4 baseline. Container images build and run on Eclipse Temurin JDK 25 (eclipse-temurin:25-jdk / 25-jre-alpine). Both are stated explicitly because the host toolchain is JDK 25 while the source level remains Java 21.

An institutional-grade, zero-Web3-SDK middleware that meters HTTP APIs with the x402 protocol and RFC 9110 §15.5.3 402 Payment Required semantics. It validates Ed25519-signed, off-chain payment vouchers in-memory in under 5ms on the request hot path, persists every verification to an append-only PostgreSQL audit ledger, and sweeps cumulative channel balances on-chain in batched settlement transactions — all without any Node.js sidecar, Python bridge, or generic Web3 Java wrapper.

AI Agent Integration (Model Context Protocol)

Autonomous AI agents can screen Solana addresses and settle compliance micro-payments through our published Model Context Protocol (MCP) server. The server is a zero-dependency x402 compliance tool: it speaks the RFC 9110 402 Payment Required challenge-and-response protocol natively, signs Ed25519 channel vouchers in-memory (Node.js built-in crypto, no Web3 SDK), and negotiates settlement on every call.

Direct Execution

npx -y @msantagiulianab/x402-mcp-server

Configuration

The server reads two environment variables:

Claude Desktop

Add an entry to claude_desktop_config.json.

macOS / Linux

{
  "mcpServers": {
    "solana-x402-compliance": {
      "command": "npx",
      "args": ["-y", "@msantagiulianab/x402-mcp-server"],
      "env": {
        "X402_GATEWAY_URL": "https://msb-solana-enterprise-payment-gateway.duckdns.org",
        "X402_CHANNEL_ID": "chan_smoke_test_001"
      }
    }
  }
}

Windows

{
  "mcpServers": {
    "solana-x402-compliance": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@msantagiulianab/x402-mcp-server"],
      "env": {
        "X402_GATEWAY_URL": "https://msb-solana-enterprise-payment-gateway.duckdns.org",
        "X402_CHANNEL_ID": "chan_smoke_test_001"
      }
    }
  }
}

VS Code Cline

Add the server to cline_mcp_settings.json:

{
  "mcpServers": {
    "solana-x402-compliance": {
      "command": "npx",
      "args": ["-y", "@msantagiulianab/x402-mcp-server"],
      "env": {
        "X402_GATEWAY_URL": "https://msb-solana-enterprise-payment-gateway.duckdns.org",
        "X402_CHANNEL_ID": "chan_smoke_test_001"
      }
    }
  }
}

Verified Dual Compliance Screening Outcomes

The screen_solana_address tool returns one of two verified outcomes:

Model Context Protocol (MCP) Server

This repository contains the official open-source MCP server implementation located at /agent-tools/mcp-server.

• Implementation: TypeScript (agent-tools/mcp-server/src)
• NPM Package: @msantagiulianab/x402-mcp-server
• Executable: npx -y @msantagiulianab/x402-mcp-server

Table of Contents

1. Executive Architecture & Core Thesis
2. System Components
3. Complete Protocol Sequence Diagram
4. Cryptographic & Voucher Wire Specification
5. HTTP Wire Headers & JSON Schemas
6. Database Schema & State Transitions
7. Quickstart & Verification
8. Configuration Parameters
9. Production Extension & Customization Guide
10. Project Layout
11. Testing
12. Security & Compliance Posture

1. Executive Architecture & Core Thesis

Problem

Base-layer blockchain latency and per-transaction fees are fundamentally incompatible with high-throughput, micro-metered HTTP APIs. Use cases such as:

• AI inference billed per token or per call,
• RWA (real-world asset) valuation feeds billed per oracle read,
• Compliance / sanctions screening billed per address,

…each issue millions of sub-cent requests per day. Settling every call directly on Solana would impose block-confirmation latency (hundreds of milliseconds to seconds) and a per-transaction fee that dwarfs the price of a single metered call. The economics do not close, and the user experience collapses.

Solution

The gateway decouples the metering decision from the settlement transaction using the x402 HTTP challenge-and-response protocol:

1. Monotonic unidirectional off-chain state channels. A client presents a signed voucher whose cumulativeAmountAtomic only ever increases for a channel. The gateway trusts the voucher only insofar as (a) it is signed by the channel owner, (b) its nonce is strictly monotonic, and (c) its cumulative spend does not exceed the verified on-chain escrow deposit.
2. RFC 9110 402 Payment Required filter. A Spring OncePerRequestFilter issues a PAYMENT-REQUIRED challenge to unauthenticated callers and accepts a PAYMENT-SIGNATURE voucher on retry, attaching a PAYMENT-RESPONSE receipt on success.
3. < 5ms hot path. Voucher verification is pure in-memory Ed25519 crypto plus a short-TTL cache of the escrow balance. No synchronous Solana RPC call is ever made on the HTTP request path.
4. Batched on-chain settlement. An administrative endpoint sweeps a channel's highest-nonce verified cumulative amount to the treasury in a single signed transaction, recorded atomically in the audit ledger.

The result is deterministic, single-digit-millisecond payment gating with fail-closed rejection, a complete audit trail, and on-chain finality only where it matters: at settlement.

Zero-Dependency Philosophy

The gateway deliberately avoids all generic Web3 SDK baggage:

There is no @solana/web3.js, no solana4j/p4j, and no runtime invocation of an external process. Wire transactions are serialized byte-by-byte from first principles, and the JVM-native crypto stack is the only third-party cryptographic primitive.

2. System Components

The gateway follows a strict layered separation:

HTTP Request
   │
   ▼
X402PaymentFilter (OncePerRequestFilter)          ── 402 challenge / 403 reject / pass-through
   │
   ├──▶ ChannelVoucherVerifier (service)          ── in-memory nonce watermark + Ed25519 + ceiling check
   │        └──▶ EscrowBalanceProvider            ── SolanaEscrowVerifier (short-TTL cache)
   │
   ├──▶ PaymentAuditService (service)             ── append VERIFIED record
   │        └──▶ PaymentAuditRepository (JPA)     ── append-only PostgreSQL ledger
   │
   └──▶ downstream @RestController               ── compliance screening, (your) metered APIs