x402 Agentic Payments Guide
Xrpl.X402 and Xrpl.X402.AspNetCore add x402 (HTTP-402) agentic payments to the XRP Ledger, implementing the t54 "XRPL exact scheme". They let an AI agent / client autonomously pay for an HTTP resource (an API, model inference, a service) in XRP or RLUSD/IOU, and let a server require payment for an endpoint.
| Package | Role |
|---|---|
| Xrpl.X402 | Client — a DelegatingHandler that detects HTTP 402, builds and locally signs an XRPL Payment, and retries with a PAYMENT-SIGNATURE header. |
| Xrpl.X402.AspNetCore | Server — a RequirePayment endpoint filter + facilitators that verify and settle the payment on-ledger. |
The client signs but does not submit — the merchant's facilitator settles the transaction (per the t54 scheme). Live interop with the t54 testnet facilitator is verified on-chain for both XRP and RLUSD/IOU.
Wire format (t54 XRPL exact scheme)
| Header | Direction | Body (base64-encoded JSON) |
|---|---|---|
PAYMENT-REQUIRED |
server → client (on 402) | { x402Version, accepts: [ {scheme:"exact", network, asset, payTo, amount, maxTimeoutSeconds, extra} ] } |
PAYMENT-SIGNATURE |
client → server | { x402Version:2, accepted, payload:{ signedTxBlob, invoiceId } } |
PAYMENT-RESPONSE |
server → client | { success, transaction, network, payer } |
assetis"XRP"(amount in drops) or a 40-hex currency code (e.g. RLUSD) withextra.issuerand a decimalamount.- The payment intent is bound to the XRPL transaction via the native
InvoiceIDfield (Payment.InvoiceID = SHA-256(invoiceId)) and/or aMemo(MemoData= hex of theinvoiceIdstring), selectable viaX402IntentBinding(defaultBoth). - t54 enforces a
SourceTag— the requirement'sextra.sourceTag(the x402 protocol value804681468) is stamped on the transaction.
Client usage
using Xrpl.Client;
using Xrpl.Wallet;
using Xrpl.X402;
IXrplClient xrpl = /* your connected IXrplClient */;
XrplWallet wallet = XrplWallet.FromSeed(seed);
// The signer autofills + signs locally (it never submits).
var signer = new XrplWalletX402Signer(xrpl, wallet);
var options = new X402ClientOptions
{
Network = "xrpl:1", // CAIP-2 network you will pay on
MaxAmountDrops = 10_000_000, // hard cap for XRP payments (10 XRP)
// IouValueCaps["rIssuer..."] = 5m, // REQUIRED to pay an IOU/RLUSD from that issuer
};
// Wrap any HttpClient with the payment handler.
var http = new HttpClient(new X402PaymentHandler(signer, options)
{
InnerHandler = new HttpClientHandler()
});
// Transparent: a 402 is paid automatically and the resource is returned.
HttpResponseMessage resource = await http.GetAsync("https://api.example.com/paid");
Security model (the merchant's 402 is treated as untrusted)
- Spending caps enforced before signing. XRP is capped by
MaxAmountDrops(always checked). IOU/RLUSD fails closed: refused unless an explicit per-issuer cap exists inIouValueCaps. - Optional
PayToAllowlist— when non-empty, bothpayToand the IOUissuermust be allow-listed. - Anti-double-pay — the client pays at most once per request; a repeated 402 throws.
- Validity window —
LastLedgerSequenceis capped by the requirement'smaxTimeoutSeconds. - All refusals throw
X402PaymentExceptionwith a machine-readableReason.
End-to-end flow (XRP)
The exchange is three HTTP steps. X402PaymentHandler performs steps 2–3 transparently inside a single GetAsync; below is what actually travels on the wire.
1. Client requests the resource — server quotes a price
GET /paid
→ 402 Payment Required
PAYMENT-REQUIRED: <base64>
Decoded PAYMENT-REQUIRED:
{
"x402Version": 2,
"accepts": [{
"scheme": "exact",
"network": "xrpl:1",
"asset": "XRP",
"payTo": "rMerchant...",
"amount": "1000000",
"maxTimeoutSeconds": 600,
"extra": { "invoiceId": "inv-123", "sourceTag": 804681468 }
}]
}
2. Client pays — retries with a signed payment
The handler selects the exact requirement on its configured network, enforces the spending caps, builds and locally signs an XRPL Payment (1 XRP to rMerchant, InvoiceID = SHA-256("inv-123"), SourceTag = 804681468), then retries with the PAYMENT-SIGNATURE header:
GET /paid
PAYMENT-SIGNATURE: <base64>
Decoded PAYMENT-SIGNATURE:
{
"x402Version": 2,
"accepted": { "scheme": "exact", "network": "xrpl:1", "asset": "XRP", "payTo": "rMerchant...", "amount": "1000000", "maxTimeoutSeconds": 600, "extra": { "invoiceId": "inv-123", "sourceTag": 804681468 } },
"payload": { "signedTxBlob": "1200002280000000...", "invoiceId": "inv-123" }
}
3. Server settles — returns the resource + a receipt
The facilitator checks the signed payment against the server's requirement, settles it on-ledger (waits for tesSUCCESS), checks what the ledger delivered, then serves the resource with a PAYMENT-RESPONSE receipt:
200 OK
PAYMENT-RESPONSE: <base64>
premium content
Decoded PAYMENT-RESPONSE:
{ "success": true, "transaction": "8DB5B4144A24E7D72FED584D8B0EAFFE19B9034FE5EC3DD296B19FED5731B7E8", "network": "xrpl:1", "payer": "rPayer..." }
Reading the receipt on the client
GetAsync returns the final 200 response; decode the PAYMENT-RESPONSE header to get the settlement result and on-ledger transaction hash:
using System.Linq;
using Xrpl.X402.Wire;
HttpResponseMessage r = await http.GetAsync("https://api.example.com/paid");
string content = await r.Content.ReadAsStringAsync(); // "premium content"
if (r.Headers.TryGetValues(X402Headers.PaymentResponse, out var values))
{
PaymentResponseEnvelope receipt = X402Base64Json.Decode<PaymentResponseEnvelope>(values.First());
Console.WriteLine($"paid: {receipt.Success}, tx: {receipt.Transaction}, payer: {receipt.Payer}");
}
Paying in RLUSD / IOU
The flow is identical — only the requirement differs, and the payer must already hold the token and a trust line to the issuer. The server quotes an issued currency:
{
"scheme": "exact",
"network": "xrpl:1",
"asset": "524C555344000000000000000000000000000000",
"payTo": "rMerchant...",
"amount": "2.50",
"maxTimeoutSeconds": 600,
"extra": {
"invoiceId": "inv-456",
"issuer": "rIssuer...",
"sourceTag": 804681468
}
}
assetis the 40-hex currency code (e.g. RLUSD),amountis a decimal string, andextra.issueris required.- The client builds an issued-currency
PaymentwhoseAmountis{ currency, issuer, value }and adds a matchingSendMax; steps 2–3 and the receipt are exactly as above. - An IOU payment fails closed unless a per-issuer cap is configured:
var options = new X402ClientOptions { Network = "xrpl:1" };
options.IouValueCaps["rIssuer..."] = 10m; // allow up to 10.0 of this issuer's token
// var http = new HttpClient(new X402PaymentHandler(signer, options) { InnerHandler = new HttpClientHandler() });
Server usage (Xrpl.X402.AspNetCore)
using Xrpl.X402.AspNetCore;
using Xrpl.X402.Wire;
IXrplClient xrpl = /* your connected IXrplClient */;
// One facilitator for every endpoint: its record of settled payments is what stops a replay.
IX402Facilitator facilitator = new LedgerSettlingFacilitator(xrpl);
// or: new T54Facilitator(new HttpClient()); // delegate to a t54 facilitator
app.MapGet("/paid", () => "premium content")
.RequirePayment(facilitator, ctx => new PaymentRequirement
{
Scheme = "exact", Network = "xrpl:1", Asset = "XRP",
PayTo = "rYourMerchantAddress...",
Amount = "1000000", // 1 XRP in drops
MaxTimeoutSeconds = 600,
Extra =
{
["invoiceId"] = JsonSerializer.SerializeToElement("inv-123"),
["sourceTag"] = JsonSerializer.SerializeToElement(804681468)
}
});
Without a PAYMENT-SIGNATURE the endpoint returns 402 + PAYMENT-REQUIRED. With a valid signature, the facilitator checks the payment (see below), settles the transaction (waits for tesSUCCESS), checks delivered_amount, sets PAYMENT-RESPONSE, and runs your handler.
Two IX402Facilitator implementations ship:
LedgerSettlingFacilitator— settles locally against your own connected node. A settlement it cannot tell the outcome of is waited for once more, then refused assettlement_unknownwith the transaction hash inPAYMENT-RESPONSE: the payer's funds may have moved, so reconcile it rather than drop it.T54Facilitator— delegates verify + settle to an external t54 facilitator over HTTP.
What LedgerSettlingFacilitator checks
RequirePayment first compares the client's accepted with the endpoint's own requirement - scheme, network, asset (exactly: currency codes are case-sensitive), payTo, amount, and extra.issuer, extra.invoiceId and extra.destinationTag - and then hands the facilitator the server's copy, so nothing the facilitator checks comes from the client. A caller that invokes a facilitator directly must pass the server's requirement in Accepted too.
Before submitting, the signed transaction must pass every check below; after validation, delivered_amount is checked. Each refusal is a 402 with its own errorReason:
errorReason |
When |
|---|---|
invalid_transaction_type |
The blob is not a Payment. A CheckCreate or EscrowCreate has a Destination too and ends in tesSUCCESS without paying. |
invalid_destination |
Destination is not payTo, or DestinationTag is not the tag of an X-address payTo or of extra.destinationTag. |
invalid_partial_payment |
tfPartialPayment is set: such a payment can deliver any fraction of Amount. |
invalid_asset |
Amount is not the required asset: drops for XRP, otherwise the currency (as text or 40 hex digits) issued by extra.issuer. An MPT amount is refused. |
invalid_amount |
Amount is not exactly the required amount. Token values are compared as numbers, so 1.0 equals 1. |
invalid_invoice_id |
extra.invoiceId is set and the transaction carries neither InvoiceID = SHA-256 of it nor a memo whose MemoData is it in hex. |
invalid_last_ledger_sequence |
No LastLedgerSequence, or one further past the validated ledger than maxTimeoutSeconds allows (at 3 seconds a ledger, at least 20 ledgers, plus 10 for a payer whose node is ahead of the facilitator's). |
payment_expired |
LastLedgerSequence is already validated: the blob can no longer enter a new ledger, so a success could only be an earlier settlement replayed. |
duplicate_payment |
The transaction hash is already settled, or is being settled. |
delivered_amount_mismatch |
The payment validated, but the metadata's delivered_amount is short of the requirement or in another asset. The response carries the transaction hash. |
Replays and the settled-payment store
A validated blob can be submitted again: the node answers tefPAST_SEQ or tefALREADY, and waiting on its hash finds the original tesSUCCESS. To stop one PAYMENT-SIGNATURE unlocking the resource twice, the facilitator claims each hash in an ISettledPaymentStore before submitting, keeps it once the payment settled, and releases it when settlement failed or its outcome stayed unknown, so the payer can present the same blob again. The default InMemorySettledPaymentStore keeps a hash until the validated ledger passes the payment's LastLedgerSequence by 256 ledgers; past its window the blob is refused as payment_expired anyway.
- Use one facilitator for every endpoint: each
new LedgerSettlingFacilitator(xrpl)has its own store, so a blob paid on one endpoint would pass another with the same price and payee. - Several instances behind a load balancer must share one store (a database or a distributed cache with an atomic insert-if-absent): the in-memory store sees only its own process.
- A store serves one network: mainnet and testnet need separate stores.
With dependency injection, AddLedgerSettlingFacilitator() registers the facilitator as the singleton IX402Facilitator over the registered IXrplClient, with the in-memory store unless an ISettledPaymentStore is registered first:
builder.Services.AddSingleton<IXrplClient>(xrpl);
// Several instances: register a shared ISettledPaymentStore here first.
builder.Services.AddLedgerSettlingFacilitator();
IX402Facilitator facilitator = app.Services.GetRequiredService<IX402Facilitator>();
Verifiable Intent
A passthrough is provided: set X402ClientOptions.VerifiableIntentProvider (an IVerifiableIntentProvider) and its extensions object is attached to each PAYMENT-SIGNATURE under x402Secure.verifiableIntentChain. The full SD-JWT L1→L3 credential chain (Mastercard Agentic / Trustline) is supplied by your own provider — this package does not generate it.
Status
- XRP and RLUSD/IOU supported. Only the
exactscheme is implemented (the only scheme t54 advertises for XRPL). - Live t54 interop confirmed on testnet for both XRP and RLUSD/IOU (
/verify→isValid:true,/settlesettles on-chain).
See the Xrpl.X402 API reference and Xrpl.X402.AspNetCore API reference for full type documentation.