XRPL Token Guard

Ask "is this token safe?" and get an honest answer with ledger evidence. An open-source MCP server and voice-assistant simulator that detect look-alike tokens on the live XRP Ledger.

Comment

Inspiration

Anyone can create a token on the XRP Ledger and call it anything. On mainnet right now there are several tokens named RLUSD that aren't Ripple's stablecoin. Most of them have a "black-holed" issuer, which simple checkers score as safe. People ask friends, Discord or an assistant "is this legit?", and the answer is usually a guess. We wanted an assistant that answers from the ledger itself, in one spoken sentence, and can say why.

What it does

XRPL Token Guard is a self-hosted MCP server with three read-only tools:

  • check_token_safety is the full live check of an XRPL token. It covers:
    • imitations of official tokens (RLUSD, USDC, SOLO)
    • issuers that can still mint, freeze or claw back
    • Global Freeze, transfer fees
    • unverified or launchpad-only domains
    • whale concentration (the AMM pool is excluded, so it isn't counted as a whale)
    • thin AMM liquidity, brand-new issuers
  • is_it_the_real_token answers "is this the real RLUSD?" instantly from verified official issuers.
  • check_wallet_security detects the classic wallet-drainer setup: a stranger's regular key or multisig signer list. It marks changes from the last 7 days as urgent.

Every answer comes in three layers:

  1. a verdict: High risk / Caution / No red flags found / Not enough data
  2. reasons, each citing the exact ledger fact
  3. a spoken_summary, written to be read aloud by Alexa+ or any voice assistant

The verdict is honest: "No red flags found" always comes with "that's not a promise". There's also a voice_token_check prompt that tells an assistant to answer in two sentences with no buy/sell advice.

The repo includes a voice-assistant simulator (the rules' "simulated Alexa+ web app" path).

  • You speak or type a question in the local simulator. It runs a real MCP client over Streamable HTTP, calls the server live and speaks the answer. The hosted demo currently supports typed questions and example chips; microphone capture is disabled by the hosting policy. This is a simulator, not an actual Alexa integration.
  • A side panel shows the actual tools/call request and result, so you can see the MCP server being called at runtime.

How we built it

  • Server: TypeScript with the official MCP TypeScript SDK (protocol 2025-11-25).
    • Streamable HTTP transport, stateless (a fresh server per request, so it scales horizontally) with JSON responses.
    • Origin allow-list, per-IP rate limit and a /health endpoint.
    • A stdio transport for desktop MCP clients.
  • Tool contracts: typed outputSchema and structuredContent, plus readOnlyHint annotations on every tool.
  • Data: public XRPL JSON-RPC with endpoint fallback and timeouts. The calls are account_info (with signer lists), gateway_balances, amm_info, account_lines and account_tx. No keys, no signing, no database.
  • Hard cases, encoded as rules:
    • Tickers are case-sensitive on-ledger, so "bigds" is resolved to the issuer's real $BIGDS.
    • The AMM pool's own balance is excluded from whale detection.
    • Regulated stablecoins are expected to keep freeze, clawback and multisig control, so those are reported as information, not warnings.
    • A locked supply never makes an imitation genuine.
    • Bridged variants like USDC.axl are told apart from outright fakes.
  • Tests: 14 automated tests (unit tests with a mocked ledger, plus end-to-end tests where a real MCP client connects over HTTP). There's also an optional live-mainnet test.
  • Docker: a Dockerfile for one-command self-hosting.

Challenges we ran into

  • RLUSD looked black-holed at first. Our first version called the real RLUSD issuer black-holed, because a type-filtered account_objects query returned an empty first page. Fetching signer lists through account_info fixed it. A regulated issuer controlled by multisig is now described correctly.
  • The AMM pool looked like a whale. Meme tokens kept showing "one wallet holds 75%". That wallet was the AMM pool, which belongs to all liquidity providers.
  • Fake answers had green ticks. A fake RLUSD's launchpad-hosted domain "verifies" itself. We now label launchpad domains as information, and a High risk answer never shows a green tick next to a fake.

Accomplishments that we're proud of

  • It catches the fake RLUSDs that are live on mainnet today, including ones a naive "is the issuer black-holed?" check would pass.
  • Each answer is short enough to speak, but every claim can still be traced to a ledger field.

What we learned

For a voice assistant, the hard part is precision under brevity. The tool's contract has to carry both the machine-precise reason and the human sentence, rather than leaving the model to paraphrase.

What's next for XRPL Token Guard

  • More verified brands (each one checked against its issuer's on-ledger Domain and xrp-ledger.toml).
  • An Alexa+ Agent Skill manifest once Alexa+ MCP connections open to developers.
  • An optional paid deep report through x402 (XRP/RLUSD), using the same tools.

Built With

Share this project:

Updates

Submission history