AgentRails.AgentFramework.X402 0.1.0

AgentRails.AgentFramework.X402

x402 payment tools for Microsoft Agent Framework (via Microsoft.Extensions.AI). Enables .NET AI agents to make HTTP requests with automatic x402 payment handling. When an API returns HTTP 402 Payment Required, the tools automatically sign a USDC payment authorization (EIP-3009) and retry the request.

Built by AgentRails — the first x402 integration for the Microsoft Agent Framework ecosystem.

Note: If you're using Semantic Kernel, see the companion package AgentRails.SemanticKernel.X402.

Installation

dotnet add package AgentRails.AgentFramework.X402

Quick Start

using AgentRails.AgentFramework.X402;
using AgentRails.AgentFramework.X402.Extensions;
using AgentRails.AgentFramework.X402.Models;
using Microsoft.Extensions.AI;

// Create x402 tools
var options = new X402PluginOptions
{
    PrivateKey = Environment.GetEnvironmentVariable("WALLET_PRIVATE_KEY")!,
    Network = "eip155:84532",  // Base Sepolia testnet
    BudgetUsd = 5.00m,
};
var wallet = new X402Wallet(options);
var httpFactory = /* your IHttpClientFactory */;
var x402 = new X402Tools(wallet, httpFactory, options);

// Register as tools on any IChatClient-based agent
IChatClient chatClient = /* your chat client (OpenAI, Azure, Ollama, etc.) */;
var response = await chatClient.GetResponseAsync(
    "Get the analysis from https://sandbox.agentrails.io/api/x402/protected/analysis",
    new ChatOptions { Tools = x402.GetTools() });
Console.WriteLine(response);

With Dependency Injection

using AgentRails.AgentFramework.X402.Extensions;

// In your service registration:
builder.Services.AddX402Tools(options =>
{
    options.PrivateKey = Environment.GetEnvironmentVariable("WALLET_PRIVATE_KEY")!;
    options.Network = "eip155:84532";
    options.BudgetUsd = 5.00m;
});

// Later, resolve and use:
var x402 = serviceProvider.GetRequiredService<X402Tools>();
var tools = x402.GetTools(); // IList<AIFunction>

appsettings.json Configuration

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

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

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 agent 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
• Agent Framework native — Exposes tools as IList<AIFunction> via AIFunctionFactory

Tools

The package exposes three AI functions:

MakePaidRequestAsync Parameters

Configuration Options

Supported Networks

How It Works

1. Your AI agent calls MakePaidRequestAsync with a URL
2. The tool 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.Extensions.AI 9.3.0+

License

MIT — see LICENSE

Links

• x402 Protocol
• AgentRails
• Microsoft.Extensions.AI
• Semantic Kernel version