Understanding permissioned domains

What it is

A Permissioned Domain (XLS-80) is an on-chain trading venue that gates participation by credential. The owner publishes a list of accepted credential issuers, and only accounts holding a valid credential from one of those issuers can match orders inside. XLS-81 extends this to permissioned market-maker offers.

Who uses them

Institutional liquidity venues, tokenized real-world-asset issuers, KYC'd OTC desks, and regulated security tokens. The first named live example on XRPL mainnet is xrp-liquid.com, with on-chain identity (XLS-40 DID) and active offers selling XRP for USDC, RLUSD, and EURQ.

How long it takes

The on-chain side is fast. Publishing a Permissioned Domain takes one transaction, about 30 seconds, and roughly $0.01 in XRP fees.

The off-chain side is slower. A useful domain needs a credential issuer, legal review, and a credential-issuance flow that gets attestations into participants' wallets. Self-attested credentials: hours. Third-party KYC and AML: days to weeks.

For developers & AI agents

Pay $0.10 per query, no API key

XR-Trust implements x402 v2 with the exact scheme on XRPL mainnet. Verification and settlement are delegated to the t54 XRPL facilitator.

1. POST /scan returns 402 Payment Required with the XRP option (RLUSD coming in a follow-up).
2. Sign an XRPL Payment matching the requirement, base64-JSON-encode it, send as PAYMENT-SIGNATURE.
3. Server verifies, looks up the domain or owner, then settles. Returns 200 with the JSON and a PAYMENT-RESPONSE header.

Swagger UI agents.json /schema

Free read-only views: GET /permissioned-domains/operators/index (paginated operator list), /permissioned-domains/operators/{addr}/attribution (auto-walker output: funder, gated assets, retail signals, narrative), and /permissioned-domains/usage-summary (ecosystem onboarding stats) all return without a payment header. Use them for dashboards; /scan stays paid for full per-domain drill-down.

Free MCP tools (5)

xrpl_trust_list_operators_index
xrpl_trust_operator_drilldown
xrpl_trust_operator_attribution
xrpl_trust_usage_summary
xrpl_trust_jurisdictions

Paid MCP tools (4)

xrpl_trust_list_domains · $0.10
xrpl_trust_get_domain · $0.10
xrpl_trust_credential_issuers · $0.10
xrpl_trust_recent_events · $0.10

Or skip the integration: call any tool above from an MCP client (Claude Desktop etc.) via @xrpl-utilities/mcp or the hosted endpoint at mcp.xrpl-utilities.io/mcp. Free tools work without a payment header; paid tools use the same x402 model wrapped as MCP arguments.

# pip install x402-xrpl

from x402_xrpl import X402RequestsSession
from xrpl.wallet import Wallet

session = X402RequestsSession(
    wallet=Wallet.from_seed(seed),
    rpc_url="https://YOUR_XRPL_RPC",
    payment_requirements_selector="XRP",
)

# look up a single domain by its 64-hex LedgerIndex
record = session.post(
    "https://trust.xrpl-utilities.io/scan",
    json={"domain_id": "AB12…"},
).json()

for match in record["matches"]:
    print(match["owner_address"],
          match["accepted_credentials"])

Output shape

What you get back

domains[]: one normalized record per PermissionedDomain ledger object
domain_id, owner_address, sequence, flags, previous_txn_id, previous_txn_lgr_seq: full XLS-80 ledger-object metadata
owner_label: external label when available ({name, desc, domain, verified, twitter}), else null
accepted_credentials[]: each entry carries {issuer, credential_type, credential_type_decoded, issuer_label}. Hex types are decoded to ASCII when printable (e.g. 4B5943 → KYC).
institutional_issuer_count + institutional_issuers[]: count and display names of distinct externally-labeled, non-self credential issuers accepted by the domain
identity_tier: one of institutional (verified TOML + DID), named_entity (TOML or DID only), funder_attributed (no TOML/DID, but parent funder is a labeled entity), credential_attributed (subject linked to a labeled issuer via accepted credential), did_only (XLS-40 DID present), or anonymous. Six-tier ladder, populated on every directory row.
Drill-down only (single-domain lookup): lifecycle (creation + last-modified meta walked from PreviousTxnID), permissioned_market (XLS-81 owner-side offers + AMMs), and identity (XLS-40 DID + parsed .well-known/xrp-ledger.toml when published)
Operator attribution (free GET /permissioned-domains/operators/{addr}/attribution): the auto-walker output. funder (parent + well-known label), domains[] with decoded credential types, credentialed_subjects[] with trustline-implied asset gating, retail_signals (self-issued-only, minimal DID, NFT objects on operator wallet, etc.), likely_retail boolean, attribution_confidence (high/medium/low), and a summary_one_line server-generated narrative. Backfilled on every walker revision bump.
Ecosystem usage (free GET /permissioned-domains/usage-summary): rolled-up onboarding activity over a configurable window: new operators, new credentials, new credentialed subjects, deletes. Right for tracking institutional adoption pace without paying per row.
total, limit, offset, next_offset, schema_version, generated_at: pagination + envelope
/credentials/issuers returns issuers[] with {issuer_address, issuer_label, domains_referencing, credential_types_issued}

Reserved fields surfaced as null in v1, populated later: member_count_estimate, verified_attestation, health_score. Full field-level details at /schema.

How it works

Reads the validated XRPL ledger directly

Source. XR-Trust reads PermissionedDomain ledger objects directly from the validated XRPL ledger. No third-party indexer, no editorial filter, no curated list. If it's on-ledger and validated, it's in the directory.

Materialization. The directory is event-driven. A persisted snapshot is hydrated on startup, kept current by an incremental refresh of every known owner, and extended in real time by a long-lived ledger-subscribe stream that picks up new owners the moment a PermissionedDomainSet from them is validated. No periodic full-ledger walk; reads stay instant.

Drill-down vs enumeration. Looking up a single domain by its domain_id is O(1) against the live ledger state. Whole-network enumeration is served from the persisted snapshot.

Owner labels. Where an external label provider recognizes a domain owner (banks, asset managers, infrastructure providers), the label appears on the directory row and the drill-down panel. Unlabeled owners surface their raw classic address.

Cross-product link. Every drill-down includes a one-click jump to XR-Sentinel to inspect the owner's on-chain behavioral pattern. Eventually the same panel will surface XR-Telemetry macro context, the XR-Pulse permissioned_domain_lifecycle event feed, and an XR-Vault link when the owner is a tracked RWA issuer; all queued for v2.

What XR-Trust is not

Descriptive directory, not a verdict

XR-Trust describes what's on-chain. We do not certify, endorse, or assess the legitimacy of any domain, owner, credential issuer, or member. Inclusion is not approval; absence is not disapproval. Not a compliance, AML, sanctions, or KYC determination; not legal or investment advice. Compliance, verification, and trust judgments remain with the consumer.

Membership in a permissioned domain is implicit (any address holding an accepted credential), and v1 does not estimate member counts.