# XR-Sentinel
Behavioral pattern classifier for XRP Ledger wallets.

## Start here (first-time integrators)
Before your first `/scan`, GET `https://sentinel.xrpl-utilities.io/schema` once and cache it. The schema document enumerates the full signal catalog, feature keys, confidence tiers, and activity-level definitions. Scan responses reference these by name/enum without inlining descriptions, so pre-loading the schema is how you map shorthand to meaning. Watch the top-level `schema_version` field to detect catalog updates and refresh your cache.

## Machine-readable discovery
- [Agent manifest](https://sentinel.xrpl-utilities.io/agents.json)
- [OpenAPI spec](https://sentinel.xrpl-utilities.io/openapi.json)
- [Interactive docs](https://sentinel.xrpl-utilities.io/docs)
- [Metric schema](https://sentinel.xrpl-utilities.io/schema)
- [Terms of service](https://sentinel.xrpl-utilities.io/tos)

## Endpoints
- `POST https://sentinel.xrpl-utilities.io/scan` - classify an XRPL address ($0.10 USD in XRP or RLUSD on XRPL, or USDC on Base, per scan). Response carries the signal catalog, activity-level tier, 30-day behavior summary, identity block, optional permissioned_domain block (XLS-80 operator drill-down when applicable), and optional whale_context block (recent INSTITUTIONAL_FLOW + WHALE_MOVE events when the wallet has been moving institutional-scale money in the trailing 30 days).
- `POST https://sentinel.xrpl-utilities.io/scan/history` - return up to 25 prior recorded scans for an address ($0.10 USD per call)
- `GET https://sentinel.xrpl-utilities.io/verify-origin?url=<origin>` - FREE. Does a web origin actually control the XRPL accounts it advertises? Cross-checks the domain's .well-known/xrp-ledger.toml, each account's Domain field (two-way, not one party's self-assertion), its XLS-40 DID, and whether every payTo in the served x402 catalog is one the domain itself declares - the check a swapped catalog fails. Also accepts `?address=<r...>` to ask what an ACCOUNT's claimed brand rests on, which is the only way to test an MPT brand claim (MPT metadata is free text nothing validates). Call this BEFORE paying an unfamiliar x402 seller.
- `GET https://sentinel.xrpl-utilities.io/proof` - FREE. Verified Record: every day whose published figures were fingerprinted (SHA3-512 Merkle root) and written to the XRP Ledger from rwty5XRq5zrqTZ7XMLgk3EqQ76V3SY8Gwy
- `GET https://sentinel.xrpl-utilities.io/proof/<YYYY-MM-DD>` - FREE. One day's record fingerprints, root and anchor transaction
- `GET https://sentinel.xrpl-utilities.io/proof/<YYYY-MM-DD>/records/<name>` - FREE. The exact stored bytes of one record, released 7 days after its date
- `GET https://sentinel.xrpl-utilities.io/stats` - operational counters and cache sizes
- `GET https://sentinel.xrpl-utilities.io/healthz` - liveness check

## Payment protocol - x402
XR-Sentinel implements x402 v2 with the `exact` scheme on two
settlement rails: XRPL mainnet (`network: "xrpl:0"`) via the t54
facilitator, and Base mainnet (`network: "eip155:8453"`) via the Coinbase
CDP x402 facilitator (api.cdp.coinbase.com/platform/v2/x402).

1. POST /scan without `PAYMENT-SIGNATURE` returns 402 with an x402 PaymentRequired body listing three `accepts[]` options when the Base rail is
   enabled (BASE_PAY_TO env set): XRP (drops, dynamic at current spot),
   RLUSD (`0.10`), and USDC on Base (`100000` atomic units, 6-decimal).
2. Pick one. For the XRPL rails, sign an XRPL Payment matching the entry
   fields. For the Base rail, sign an EIP-3009 `transferWithAuthorization`
   from your EVM wallet. Base64(JSON) the PaymentPayload envelope and send as
   `PAYMENT-SIGNATURE` on retry.
3. On HTTP 200, the `PAYMENT-RESPONSE` header carries the base64(JSON) settlement result (`success`, `transaction`, `network`, `payer`).

Reference clients: `x402-xrpl` (PyPI) for the XRPL rails; the official
`x402` package with `[evm]` extras for the Base USDC rail.

## Provenance
Every 200 answer on a paid route carries a `provenance` block: service, schema_version, served_at and the newest validated XRP Ledger the service had read (index, hash, close_time). Field meanings are under `provenance` in /schema.

## Payment finality
Verify-before-settle: if the AI classification step fails (HTTP 503), settlement does NOT happen and your presigned tx is never broadcast - retry the same payment within the freshness window. Successful classifications and cached responses are paid; no refunds otherwise.

## Available via MCP
Both /scan and /scan/history are also exposed as Model Context Protocol tools (`xrpl_sentinel_scan`, `xrpl_sentinel_scan_history`) at `https://mcp.xrpl-utilities.io/mcp` and via the npm package `@xrpl-utilities/mcp`. The MCP server is a stateless passthrough proxy - same x402 payment flow, same `$0.10 USD` per call, same response shape; callers just pass `payment_signature` as a tool arg instead of an HTTP header. See https://github.com/XRPL-Utilities/xrpl-utilities-mcp for Claude Desktop config and tool definitions.
