Integración de pagos de Semantic Kernel.
No se necesita ningún paquete Semantic Kernel. Envuelve el cliente real de blockchain0x en una KernelFunction (Python o Java), o llama a la API REST desde una KernelFunction de C#. De cualquier manera, el agente mueve USDC en Base.
No hay paquete de Semantic Kernel. En Python envuelves el cliente real de blockchain0x en un método decorado con @kernel_function; en C#, donde no se envía ningún SDK de .NET, un [KernelFunction] llama a la API REST directamente. Regístralo en tu kernel, establece FunctionChoiceBehavior en Auto, y el agente puede mover USDC en Base. Los SDKs principales enviados son Node, Python, Ruby, Go y JVM.
El único marco de agente .NET de nivel empresarial.
Si tu stack es de forma Microsoft (Azure, .NET, SQL Server, Teams, Copilot Studio), Semantic Kernel es casi con seguridad el marco de agente adecuado. Está construido por Microsoft, se integra con Azure OpenAI, AKS y Entra, y tiene soporte de primera clase en .NET, Python y Java de una manera que ningún otro marco iguala. Y ya te da lo que necesitas: una KernelFunction es solo un método, por lo que conectar pagos es un método que escribes, no un paquete que esperas.
Esa es la razón por la que no hay un adaptador de Semantic Kernel para instalar. En Python y Java envuelves el SDK real de blockchain0x en una KernelFunction; en C#, donde aún no se envía ningún SDK de .NET, la KernelFunction llama a la API REST directamente con HttpClient. Mantienes la ergonomía idiomática - métodos decorados, async, validación de parámetros basada en atributos - y no hay versión de adaptador que rastrear. Los SDKs principales que existen hoy son Node, Python, Ruby, Go y JVM.
Instala Semantic Kernel y, en Python, el SDK principal.
No hay paquete de blockchain0x Semantic Kernel para agregar. Python instala Semantic Kernel más el verdadero SDK de blockchain0x; C# instala Microsoft.SemanticKernel y llama a la API REST con el HttpClient incorporado. Java utiliza Semantic Kernel para Java más el SDK com.blockchain0x:sdk-jvm.
pip install semantic-kernel blockchain0xdotnet add package Microsoft.SemanticKernelBLOCKCHAIN0X_API_KEY=sk_test_... # sk_test_ = Base Sepolia, sk_live_ = Base mainnet BLOCKCHAIN0X_API_KEY=sk_test_... # same key, the name the .NET REST example reads OPENAI_API_KEY=sk-...
BLOCKCHAIN0X_API_KEY (el cliente de Python lee esto) es una clave sk_test_ testnet o sk_live_ mainnet de tu panel de control; el ejemplo REST de C# lee el mismo valor de BLOCKCHAIN0X_API_KEY. OPENAI_API_KEY (o AZURE_OPENAI_* para modelos alojados en Azure) es tu clave LLM. El manejador de webhook también necesita BLOCKCHAIN0X_WEBHOOK_SECRET.
Una KernelFunction de billetera, en Python y C#.
Python envuelve el cliente real de blockchain0x en un método decorado con @kernel_function. C#, donde no se envía ningún SDK de .NET, expone un [KernelFunction] que llama directamente a POST /v1/payments con HttpClient. Ambos se registran en el kernel como Wallet.send_usdc; solo difiere la ceremonia circundante.
from semantic_kernel import Kernel from semantic_kernel.functions import kernel_function from blockchain0x import Client blockchain0x = Client() # reads BLOCKCHAIN0X_API_KEY from the environment class WalletPlugin: @kernel_function(description="Send a USDC payment from an agent wallet.") def send_usdc(self, agent_id: str, to: str, amount_wei: str) -> str: # amount_wei is USDC base units (6 decimals): "10000" = 0.01 USDC return str( blockchain0x.payments.create(body={"agentId": agent_id, "to": to, "amountWei": amount_wei}) ) kernel = Kernel() kernel.add_plugin(WalletPlugin(), plugin_name="Wallet") # Add your chat service, then let the model call Wallet.send_usdc.
using System.ComponentModel;
using System.Net.Http.Json;
using Microsoft.SemanticKernel;
// There is no .NET SDK, so a C# KernelFunction calls the REST API directly.
public class WalletPlugin
{
private static readonly HttpClient Http = new()
{
BaseAddress = new Uri("https://api.blockchain0x.com"),
};
[KernelFunction, Description("Send a USDC payment from an agent wallet. amountWei is USDC base units (6 decimals).")]
public async Task<string> SendUsdc(string agentId, string to, string amountWei)
{
Http.DefaultRequestHeaders.Authorization =
new("Bearer", Environment.GetEnvironmentVariable("BLOCKCHAIN0X_API_KEY"));
var res = await Http.PostAsJsonAsync("/v1/payments", new { agentId, to, amountWei });
return await res.Content.ReadAsStringAsync();
}
}
// builder.Plugins.AddFromType<WalletPlugin>("Wallet");Register the function on the kernel, set FunctionChoiceBehavior to Auto, and when the user's message implies a payment the model calls Wallet.send_usdc with the agent id, recipient, and amount. amountWei is base units, so 0.01 USDC is "10000". The Python path returns the SDK result; the C# path returns the REST response body.
API mínima de ASP.NET Core para recibir eventos de pago.
Cuando un pago se liquida, Blockchain0x envía un evento firmado a tu URL de webhook. No hay verificador .NET enviado, por lo que el manejador verifica manualmente contra el HMAC documentado - que es todo lo que haría un ayudante. Ejemplo de .NET a continuación; Python y Java verifican de la misma manera con sus propias bibliotecas HMAC.
using System.Security.Cryptography;
using System.Text;
using Microsoft.AspNetCore.Builder;
var app = WebApplication.CreateBuilder(args).Build();
var secret = Environment.GetEnvironmentVariable("BLOCKCHAIN0X_WEBHOOK_SECRET")!;
app.MapPost("/webhooks/payment", async (HttpRequest req) =>
{
using var reader = new StreamReader(req.Body);
var raw = await reader.ReadToEndAsync(); // RAW body - verify before parsing
var sig = req.Headers["X-Blockchain0x-Signature"].ToString();
var ts = req.Headers["X-Blockchain0x-Timestamp"].ToString();
var parts = sig.Split(',').Select(p => p.Split('=', 2))
.Where(p => p.Length == 2).ToDictionary(p => p[0], p => p[1]);
var t = parts.GetValueOrDefault("t", ts);
var v1 = parts.GetValueOrDefault("v1", sig);
var want = Convert.ToHexString(new HMACSHA256(Encoding.UTF8.GetBytes(secret))
.ComputeHash(Encoding.UTF8.GetBytes($"{t}.{raw}"))).ToLowerInvariant();
var fresh = Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - long.Parse(t)) <= 300;
if (!fresh || !CryptographicOperations.FixedTimeEquals(
Encoding.UTF8.GetBytes(want), Encoding.UTF8.GetBytes(v1)))
return Results.Unauthorized();
if (req.Headers["X-Blockchain0x-Event-Type"] == "payment.received")
await RunFollowupAsync(); // USDC landed - do the next step
return Results.Ok();
});
app.Run();El algoritmo es HMAC-SHA256 sobre la cadena t.rawBody, una ventana de repetición de 300 segundos y una comparación en tiempo constante. Lee el cuerpo sin procesar a través de StreamReader para que la firma permanezca intacta; no deserialices y luego re-serialices. Los eventos enviados son payment.received, payment.sent, wallet.deployed y webhook.test. En producción, el webhook a menudo se ejecuta como un servicio separado de ASP.NET Core compartiendo una base de datos con el agente para que ambos puedan coordinarse.
Los SDKs y la superficie REST son abiertos. Léelos.
No hay un paquete de inicio de Semantic Kernel para clonar - las recetas anteriores son la integración. Los SDKs principales de blockchain0x (Node, Python, Ruby, Go) son de código abierto en GitHub, y su superficie de métodos más las rutas REST que llama el ejemplo de C# están documentadas en la documentación.
docs.blockchain0x.com/docs/overviewLa superficie de métodos del SDK y las rutas REST están documentadas en la documentación. Comienza con una clave sk_test_ contra Base Sepolia, luego cambia a sk_live_ cuando la KernelFunction haga lo que esperas.
Cinco trampas específicas de Semantic Kernel a evitar.
El modelo de plugin de Semantic Kernel es limpio, pero tiene trampas de comportamiento y de lenguaje cruzado. Conocerlas de antemano ahorra tiempo.
No hay paquete de Semantic Kernel, en ningún idioma
No hay adaptador de NuGet, PyPI o Maven. Los SDKs principales enviados son Node, Python, Ruby, Go y JVM - no .NET. Así que un kernel de Python envuelve el cliente de Python de blockchain0x en un @kernel_function, un kernel de Java utiliza el SDK com.blockchain0x:sdk-jvm, y un kernel de C# llama a la API REST directamente desde un KernelFunction (mostrado arriba). Los tres son unas pocas líneas.
FunctionChoiceBehavior debe ser Auto
El Semantic Kernel solo invoca funciones de complemento cuando FunctionChoiceBehavior está configurado en Auto en la configuración de ejecución de avisos. El valor predeterminado es Ninguno, por lo que el modelo nunca llama a tu función de billetera sin importar cuán claramente lo pida el usuario. Si el agente ignora la función por completo, verifica esto primero.
Las cantidades son unidades base de USDC, como cadenas
The payments call takes amountWei: a string of USDC base units (6 decimals), so 0.01 USDC is "10000" and 5 USDC is "5000000". Type the function argument as a string in any language. payments.create also does not retry by default and can answer 503 until the chain adapter is wired for your network - return a clear message rather than letting the agent loop.
Alcance del plugin entre agentes
Registra la función de billetera solo en el núcleo del agente que debe tener la autoridad de gasto. El complemento no es global - un agente cuyo núcleo no lo tiene no puede llamarlo. Da a un agente revisor un núcleo sin la función de billetera, o restringe las funciones permitidas por agente, para que el dinero se mantenga en un solo rol.
Verificar webhooks contra el cuerpo sin procesar
Lee el cuerpo de la solicitud sin procesar y verifica antes de deserializar - el HMAC cubre los bytes exactos, por lo que un viaje de ida y vuelta de analizar y luego volver a serializar lo rompe. El controlador .NET a continuación implementa el algoritmo documentado: HMAC-SHA256 sobre t.rawBody, una ventana de 300 segundos y una comparación en tiempo constante. Python y Java verifican de la misma manera con sus propias bibliotecas HMAC.