Xrpl.X402.AspNetCore 1.1.0

Xrpl.X402.AspNetCore

Server-side of x402 (HTTP-402) agentic payments for the XRP Ledger. Protect an ASP.NET Core endpoint so it requires an XRPL payment (XRP or RLUSD/IOU) before serving — the t54 "XRPL exact scheme".

Pairs with the client package Xrpl.X402. Builds on the Xrpl SDK.

📖 Full documentation — end-to-end flow (price → pay → receipt) with XRP and RLUSD/IOU examples: x402 Agentic Payments Guide · API reference.

What it adds

Usage

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.
// Separate instances keep separate records, so a blob paid on one endpoint would pass another.
IX402Facilitator facilitator = new LedgerSettlingFacilitator(xrpl);
// or: IX402Facilitator facilitator = new T54Facilitator(new HttpClient());

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) // t54 enforces SourceTag
       }
   });

Without a PAYMENT-SIGNATURE the endpoint returns 402 + the PAYMENT-REQUIRED challenge. With a valid signature, the facilitator verifies the payment, settles the transaction, sets PAYMENT-RESPONSE, and your handler runs. Implement IX402Facilitator for any other facilitator.

What LedgerSettlingFacilitator refuses

The payment is checked against the endpoint's own requirement: RequirePayment compares the client's accepted with it (including extra.issuer, extra.invoiceId and extra.destinationTag) and then hands the facilitator the server's copy. A caller that invokes a facilitator directly must do the same.

Resubmitting a validated blob makes the node report the original tesSUCCESS, so the facilitator keeps the hash of every payment it settled until the payment's window has passed. Keep one facilitator for the application, or register it through AddLedgerSettlingFacilitator():

builder.Services.AddSingleton<IXrplClient>(xrpl);
// Several instances behind a load balancer: register a shared ISettledPaymentStore here first.
// A store serves one network; mainnet and testnet need separate ones.
builder.Services.AddLedgerSettlingFacilitator();

IX402Facilitator facilitator = app.Services.GetRequiredService<IX402Facilitator>();

See the Xrpl.X402 README for the full wire format, client usage, security model, and t54 interop notes.

License

Apache-2.0. Part of XrplCSharp.