XRPL Financial Intelligence

XRPL Financial Intelligence is an MCP-accessible, x402-monetized financial intelligence service that allows autonomous agents to purchase specialized XRPL market, risk, liquidity and allocation analysis and use the results in their own economic decisions.

Commercial Loop

                    ┌──────────────┐
                    │  BUYER AGENT │
                    └──────┬───────┘
                           │
                    "I need a decision"
                           │
                           ▼
                    ┌──────────────┐
                    │     MCP      │
                    │  Discovery   │
                    └──────┬───────┘
                           │
                    "Call this tool"
                           │
                           ▼
                    ┌──────────────┐
                    │   x402       │
                    │   Payment    │
                    └──────┬───────┘
                           │
                      XRPL payment
                           │
                           ▼
                ┌────────────────────┐
                │ Financial          │
                │ Intelligence       │
                │ Engine             │
                └─────────┬──────────┘
                          │
                   Structured result
                          │
                          ▼
                    ┌──────────────┐
                    │  BUYER AGENT │
                    │  acts on it  │
                    └──────────────┘

Architecture

package.json, tsconfig.json, vitest.config.ts, .env.example, .gitignore
mandates/treasury-100k.json          the demo mandate
scripts/setup-wallets.ts             funds seller + buyer testnet wallets, writes .env
src/shared/types.ts                  Mandate, PoolSnapshot, PoolMetrics, AllocationResult, AuditEvent
src/shared/currency.ts               hex currency code → display symbol
src/shared/audit.ts                  AuditLog: append JSONL events per run
src/engine/scoring.ts                feeApy, riskScore, liquidityScore, scorePool (pure)
src/engine/optimizer.ts              optimizeAllocation (pure)
src/engine/xrplData.ts               discoverPools (xrpscan), fetchPoolState (amm_info), sampleVolume (account_tx)
src/engine/engine.ts                 listOpportunities, runAnalysis (orchestration)
src/seller/mcp.ts                    buildMcpServer: list_opportunities (free), optimize_allocation (payment_required)
src/seller/app.ts                    buildSellerApp: /health, /mcp, x402-guarded /api/optimize_allocation
src/seller/index.ts                  seller entry
src/buyer/spendPolicy.ts             SpendTracker
src/buyer/pay.ts                     payForResource via x402Purchase
src/buyer/mcpClient.ts               connectMcp, mcpToolsToOpenAiTools
src/buyer/agent.ts                   runAgentLoop (OpenAI Responses loop, injectable)
src/buyer/index.ts                   buyer entry
src/dashboard/index.ts               dashboard server: /api/runs, /api/runs/:id, static page
src/dashboard/public/index.html      audit timeline UI
tests/**/*.test.ts                   one test file per source module
runs/                                JSONL audit logs (gitignored)

The seller is an Express server exposing a stateless MCP endpoint at /mcp (discovery and a paid tool) plus an x402-guarded REST resource at /api/optimize_allocation that runs the intelligence engine. The buyer is a GPT-5.6 Sol tool-use loop whose tool list is built dynamically from MCP listTools, plus two local tools: pay_for_resource (x402 purchase under a spend policy) and record_decision. The buyer calls the OpenAI Responses API with model gpt-5.6-sol (override with OPENAI_MODEL) and reasoning.effort set to low. The dashboard serves an audit trail of every run written as JSONL.

How MCP and x402 Divide the Work

MCP (Model Context Protocol) handles discovery and contract. The list_opportunities tool is free and returns a list of XRPL AMM pools with depth and fee only; no scores, no recommendation. The optimize_allocation tool returns a payment_required envelope indicating the cost.

x402 (HTTP 402 Payment Required) handles payment. When the buyer agent calls optimize_allocation, it receives a payment-required envelope. The agent evaluates whether the analysis is worth the price. If yes, it calls the local pay_for_resource tool, which executes an x402 purchase with the buyer's wallet. The buyer's wallet enforces the spend policy inside the x402 requirement selector before signing: declines are logged as payment_declined.

The payment is settled by the t54 testnet facilitator on network xrpl:1. Once settlement confirms, the buyer receives the analysis via the REST response body at POST /api/optimize_allocation.

Intelligence Model

The MVP heuristic evaluates XRPL AMM opportunities and produces a risk-adjusted allocation recommendation. This model is not a validated risk framework and is appropriate for a hackathon demo only.

Risk Score (0–100 scale, lower is better):

Start at 20.
If the asset issuer is in the RLUSD allowlist (rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De): +0. Else if the issuer is xrpscan-verified: +20. Else: +40.
If TVL is below 50,000 XRP: +25. Else if below 250,000 XRP: +10.
If trading fee exceeds 500 (the AMM fee unit is 1/100,000, so 500 equals 0.5%, or 50 basis points): +10.
If the asset is frozen: +30.
Clamp to 0–100.

Liquidity Score (0–100 scale, higher is better):

share = deployXrp / tvlXrp.
score = round(100 * (1 - min(1, share * 5))).
Deploying 20% of a pool scores 0; deploying 5% scores 75.

Fee APY:

feeApy = volumeXrpPerDay * (tradingFee / 100000) * 365 / tvlXrp.
Volume is estimated from absolute XRP balance changes on the AMM account over the sampled span (up to 200 recent transactions).

Risk-Adjusted Score:

riskAdjustedScore = feeApy * (1 - risk / 100).

Allocation Algorithm:

Reserve = amount * minimum_liquidity. Deployable = amount - reserve.
Eligible pools: riskScore <= mandate.maximum_risk_score, liquidityScore >= 50, !frozen, feeApy > 0. Sort by risk-adjusted score descending.
For each eligible pool while deployable > 0: allocate min(amount * maximum_protocol_allocation, deployable). Subtract from deployable.
Leftover deployable capital joins the liquid reserve.
Expected APY is the weight-average of pool fees. Portfolio risk and liquidity are weighted over deployed lines only.
Recommendation is the pairLabel of the first allocated pool, or "hold_liquid" if none qualify.
Valid for 1 hour.

Limitation: LP positions on AMM pools carry XRP price exposure that this model does not account for. Holding RLUSD liquidity and deploying to XRP/RLUSD creates basis risk if XRP appreciates or depreciates significantly. Agents must incorporate XRP price forecasts separately.

Run It

Live mainnet data is read-only via xrpscan pool discovery and mainnet JSON-RPC calls. Testnet wallets and x402 payment flow operate on XRPL testnet.

npm install
npm run setup:wallets      # funds two testnet wallets, writes .env
# set OPENAI_API_KEY in .env
npm run seller             # shell 1
npm run dashboard          # shell 2, http://127.0.0.1:8090
npm run buyer              # shell 3
npm test

npm install: Install dependencies.
npm run setup:wallets: Funds a seller wallet and a buyer wallet with 100 XRP each from the testnet faucet, writes XRPL_PAY_TO and XRPL_BUYER_SEED to .env.
Set OPENAI_API_KEY in .env (required for the buyer agent). OPENAI_MODEL defaults to gpt-5.6-sol.
npm run seller (shell 1): Start the MCP server and x402-guarded API on http://127.0.0.1:8080.
npm run dashboard (shell 2): Start the audit-trail dashboard on http://127.0.0.1:8090.
npm run buyer (shell 3): Run the buyer agent against the mandate in mandates/treasury-100k.json. The agent discovers tools via MCP, decides whether to pay, executes an x402 transaction if approved, receives the analysis, and records a decision.
npm test: Run all 53 tests across 14 test files. All tests pass; typecheck is clean.

Evidence

Seller wallet (payment recipient): rhWLqJ2mpNNBmFe5TSDQKEBXKiPKdZkPaR (funded 100 XRP on 2026-09-05)

Buyer wallet (payment sender): rU6pvGTCWxihsb6sHnCkBfch64C6cxLxC6 (funded 100 XRP on 2026-09-05)

Service pricing: optimize_allocation costs 500,000 drops (0.5 XRP)

Live end-to-end run (2026-09-04, run id 20260904T234325-a1f29c):

Payment: 500,000 drops from the buyer wallet to the seller wallet, SourceTag 804681468, validated in testnet ledger 20490630 with result tesSUCCESS.
Transaction hash: 30C66AA9576837870B88984C5D649F2065E6AA40BA62B96D5D328E9258F4C756
Explorer: https://testnet.xrpl.org/transactions/30C66AA9576837870B88984C5D649F2065E6AA40BA62B96D5D328E9258F4C756
Audit trail: runs/20260904T234325-a1f29c.jsonl (mandate, discovery, tool calls, payment_required, payment_settled, result, decision).
Purchased analysis: 12 mainnet pools considered, 11 rejected on risk or depth; XRP/RLUSD selected with fee APY 1.46%, risk score 20, liquidity score 97.
Agent decision: allocate 25,000 RLUSD (25%) to the XRP/RLUSD AMM pool and hold 75,000 RLUSD (75%) liquid, citing the 25% per-pool cap, the risk ceiling of 30, and the 50% liquidity floor.

An earlier attempt in the same session failed verification with verify_failed:source_tag_mismatch until the seller advertised extra.sourceTag; the agent then recorded a hold-liquid decision, which is the intended behaviour when paid intelligence is unavailable.

Trust and Safety

The buyer agent enforces strict spending limits inside its wallet:

Maximum 1,000,000 drops (1 XRP) per request.
Maximum 3,000,000 drops (3 XRP) per run.
Above these limits, payments are declined and logged as payment_declined.

The service never takes custody of buyer funds. The buyer only recommends an allocation; it does not execute RLUSD transfers or AMM deposits. A human operator or downstream automation must execute trades based on the recommendation.

Every run produces a JSONL audit trail at runs/<runId>.jsonl, one JSON record per line with runId, seq, ts, event. Each event records the mandate, discovered tools, tool calls, payment requirements, transaction hashes, analysis results, and final decisions. The dashboard at http://127.0.0.1:8090 renders the audit trail for review.

The service operates on XRPL testnet only. Mainnet data is read-only; no transactions are submitted to mainnet.

Hackathon Feedback Hook

.claude/settings.json and hook/ contain the XRPL feedback hook required by the Singhacks 2026 hackathon. These must remain in the repository.

Not Built

A full DeFi protocol. We do not operate our own lending market, DEX, or yield protocol.
A custodial asset manager. We do not take custody of customer funds.
A generic AI chatbot. Conversational interface is secondary.
A generic yield aggregator. We do not reproduce a dashboard showing APYs.
A retail investment application. The primary interface is machine-to-machine.
An AI that autonomously invests unlimited money. Agent autonomy is constrained by spend policies.
A claim that autonomous XRPL treasury agents already dominate the market. This hackathon prototype demonstrates the infrastructure and business primitive for a future agent economy.