AgentRails.SemanticKernel.X402 0.1.0

AgentRails.SemanticKernel.X402

A Semantic Kernel plugin that enables AI agents to make HTTP requests with automatic x402 payment handling. When an API returns HTTP 402 Payment Required, the plugin automatically signs a USDC payment authorization (EIP-3009) and retries the request.

Built by AgentRails — the first x402 integration for the Microsoft/.NET AI ecosystem.

Installation

dotnet add package AgentRails.SemanticKernel.X402

Quick Start

using AgentRails.SemanticKernel.X402;
using AgentRails.SemanticKernel.X402.Extensions;
using Microsoft.SemanticKernel;

var builder = Kernel.CreateBuilder();
builder.AddOpenAIChatCompletion("gpt-4o", Environment.GetEnvironmentVariable("OPENAI_API_KEY")!);

// Register x402 plugin
builder.Services.AddX402Plugin(options =>
{
    options.PrivateKey = Environment.GetEnvironmentVariable("WALLET_PRIVATE_KEY")!;
    options.Network = "eip155:84532";  // Base Sepolia testnet
    options.BudgetUsd = 5.00m;         // Max spend per session
});
builder.Plugins.AddFromType<X402Plugin>();

var kernel = builder.Build();

// The agent will automatically pay for x402-protected APIs
var result = await kernel.InvokePromptAsync(
    "Get the analysis from https://sandbox.agentrails.io/api/x402/protected/analysis");
Console.WriteLine(result);

Features

• Automatic 402 handling — Detects HTTP 402 responses, signs EIP-3009 payment authorizations, retries transparently
• Budget management — Per-session USD budget with real-time tracking
• Thread-safe — Safe for concurrent use across multiple kernel invocations
• x402 V2 compliant — Supports V2 protocol with V1 backwards compatibility
• Multi-network — Base Sepolia, Ethereum Sepolia, Arc Testnet, Base Mainnet, Ethereum Mainnet
• Local signing — Uses Nethereum for local EIP-712 signing, no external services required

Plugin Functions

The plugin exposes three functions to the AI agent:

make_paid_request Parameters

Configuration

Lambda Configuration

builder.Services.AddX402Plugin(options =>
{
    options.PrivateKey = "your-hex-private-key";
    options.Network = "eip155:84532";
    options.BudgetUsd = 10.00m;
    options.DefaultMaxPriceUsd = 1.00m;
    options.AutoPay = true;
    options.TimeoutSeconds = 30;
});

appsettings.json Configuration

{
  "X402": {
    "PrivateKey": "your-hex-private-key",
    "Network": "eip155:84532",
    "BudgetUsd": 10.00,
    "DefaultMaxPriceUsd": 1.00,
    "AutoPay": true,
    "TimeoutSeconds": 30
  }
}

builder.Services.AddX402Plugin(configuration.GetSection("X402"));

Options

Supported Networks

How It Works

1. Your AI agent decides to call make_paid_request with a URL
2. The plugin makes the HTTP request
3. If the server returns 200 OK, the response is returned directly
4. If the server returns 402 Payment Required:
   • Parses the PAYMENT-REQUIRED header (V2) or X-PAYMENT-REQUIRED (V1)
   • Finds a compatible payment option matching the wallet's network
   • Checks the price against the per-request limit and session budget
   • Signs an EIP-3009 TransferWithAuthorization message locally
   • Retries the request with the PAYMENT-SIGNATURE header
   • Returns the response prefixed with payment details

Security

• Private keys stay local — All signing happens in-process using Nethereum. No keys are ever sent over the network.
• Budget enforcement — Hard USD cap prevents runaway spending. Thread-safe budget tracking.
• Per-request limits — Each request has a configurable max price. The agent can also set limits per-call.
• AutoPay toggle — Set AutoPay = false to require explicit approval before any payment.

Requirements

• .NET 8.0+
• Microsoft Semantic Kernel 1.30.0+

License

MIT — see LICENSE

Links

• x402 Protocol
• AgentRails
• Semantic Kernel