x402.Client

x402-dotnet

x402 Payment Protocol implementation for .Net

x402 on the server

Install the x402 packages from NuGet:

• x402
• x402.Coinbase

Features:

• Add an x402-compatible paywall to any URL
• Easily use an attribute to handle payments for your API methods
• Add URLs that require payment using the middleware
• Support advanced scenarios by calling the X402Handler in your API controller
• Handle payment settlement using any remote facilitator
• Optionally use the Coinbase facilitator (with API key)
• Extensible TokenInfoProvider that fills in network and coin data based on the asset address

x402 enabled HttpClient

Install the x402.Client.EVM package from NuGet:

• x402.Client.EVM

Features:

• Transparant access x402-protected resources
• Fully HttpClient compatible
• Pay using the embedded EVM compatible wallet (Ethereum / Base)
• Set allowances per request or globally
• X402.Client.ConsoleSample sample application included

How to use?

Register the x402 services and facilitator in Program.cs:

// Use the default HttpFacilitator
builder.Services.AddX402().WithHttpFacilitator(facilitatorUrl);

Use the PaymentRequired Attribute

// Use the Payment Required Attribute
[HttpGet]
[Route("protected")]
[PaymentRequired("1000", "0x036CbD53842c5426634e7929541eC2318f3dCF7e", "0xYourAddressHere")]
public SampleResult Protected()
{
    return new SampleResult { Title = "Protected by PaymentRequired Attribute" };
}

Directly in an API Controller (for more control)

public ResourceController(X402Handler x402Handler)
{
    this.x402Handler = x402Handler;
}

[HttpGet]
[Route("dynamic")]
public async Task<SampleResult?> Dynamic(string amount)
{
    var x402Result = await x402Handler.HandleX402Async(this.HttpContext, facilitator, fullUrl,
        new PaymentRequirementsBasic
        {
            Asset = "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
            Description = "Dynamic payment",
            MaxAmountRequired = amount,
            PayTo = "0x7D95514aEd9f13Aa89C8e5Ed9c29D08E8E9BfA37",
        });

    if (!x402Result.CanContinueRequest)
    {
        return null; // Response already written by HandleX402Async, so just exit
    }

    //Continue with the request
}

Or use the PaymentMiddleware to require payment for a list of URLs

// Add Middleware
var paymentOptions = new PaymentMiddlewareOptions
{
    PaymentRequirements = new Dictionary<string, PaymentRequirementsConfig>()
    {
        {  "/resource/middleware", new PaymentRequirementsConfig
            {
                PaymentRequirements = new PaymentRequirementsBasic {
                    MaxAmountRequired = "1000",
                    Asset = "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                    MimeType = "application/json",
                    Description = "Payment Required",
                    Discoverable = true,
                    PayTo = "0x7D95514aEd9f13Aa89C8e5Ed9c29D08E8E9BfA37", // Replace with your actual wallet address
                }
            }
        }
    },
};

app.UsePaymentMiddleware(paymentOptions);

Coinbase Facilitator

To use the Coinbase Facilitator, install x402.Coinbase

// Add the Coinbase Config and Facilitator
builder.Services.AddX402().WithCoinbaseFacilitator(builder.Configuration);

Add to appsettings.json:

 "CoinbaseOptions": {
   "ApiKeyId": "YOUR_COINBASE_API_KEY_ID",
   "ApiKeySecret": "YOUR_COINBASE_API_KEY_SECRET"
 }

x402 HttpClient

// Fixed private key (32 bytes hex)
var wallet = new EVMWallet("0x0123454242abcdef0123456789abcdef0123456789abcdef0123456789abcdef", chainId) //84532UL = base-sepolia
{
    IgnoreAllowances = true
};

var handler = new PaymentRequiredHandler(wallet);

var client = new HttpClient(handler);
var response = await client.GetAsync("https://www.x402.org/protected");

Console.WriteLine($"Final: {(int)response.StatusCode} {response.ReasonPhrase}");

See X402.Client.ConsoleSample for a complete example.

How to test?

Follow these steps to test a x402 payment on the sample website hosted on Azure:

• Get some USDC tokens on the base-sepolia network from the Coinbase Faucet
• Use the x402 Debug Tool: https://proxy402.com/fetch
• Enter an API endpoint from the test website, for example: https://x402-dotnet.azurewebsites.net/resource/middleware
• Connect your wallet
• Click Pay
• Payment will complete and show the result: Protected by middleware

Facilitators

List of facilitators you can use:

• https://api.cdp.coinbase.com/platform/v2/x402/ (Coinbase, requires API key)
• https://facilitator.payai.network
• https://facilitator.mogami.tech/
• https://facilitator.mcpay.tech (Proxy Facilitator)

View more facilitators and their status on https://x402dev.com

Development

There is a sample website and mock Settlement server included.

• Start the Aspire project: x402-dotnet.AppHost
• Navigate to the sample website https://localhost:7154/
• Use x402.SampleWeb.http for sample web requests

Contributions

Contributions are welcome. Fork this repository and send a pull request if you have something useful to add.

Links

Useful tools when developing x402 solutions:

• More info about x402: https://www.x402.org
• Test tool± https://proxy402.com/fetch
• Specifications: https://github.com/coinbase/x402/blob/main/specs/x402-specification.md