Migrar desde Stripe a Blockchain0x para acceso a la API impulsado por agentes.
No reemplace Stripe; ejecútelo junto a él. Una sola puerta frontaliza cada punto final protegido con dos métodos de autenticación: una suscripción activa de Stripe (para humanos), de lo contrario, el adaptador del lado de recepción x402 (para agentes), que emite un desafío 402 y verifica el encabezado X-Payment en el reintento. La lógica del controlador no cambia.
Antes de comenzar.
- Una integración funcional de Stripe con al menos un producto/precio activo (suscripción o único).
- Un perfil de agente de Blockchain0x y una clave API (consulta agregar pagos al agente).
- Una capa de autenticación/middleware en tu marco web donde actualmente llamas a Stripe para restringir el acceso.
- Un mecanismo de bandera de características (variable de entorno, LaunchDarkly, booleano simple - cualquier cosa que te permita alternar el comportamiento sin redeployar).
- Comprensión del x402 pattern - el decorador a continuación lo implementa.
Escribe la puerta de autenticación dual.
La puerta es la única pieza de pegamento. Primero verifica si hay una suscripción activa de Stripe (el camino humano); si no hay ninguna, entrega la solicitud al adaptador del lado de recepción x402 (el camino del agente), que emite el desafío 402 y verifica el encabezado X-Payment cuando el agente reintenta. El ejemplo de Node utiliza createX402Middleware; un servicio de Python habla el mismo cable a mano.
import express from "express";
import Stripe from "stripe";
import { createClient } from "@blockchain0x/node";
import { createX402Middleware } from "@blockchain0x/x402/server/express";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const sdk = createClient({ apiKey: process.env.BLOCKCHAIN0X_API_KEY! });
// Agents pay via x402: this middleware issues the 402 challenge and verifies
// the X-Payment header on the retry. Configure price + recipient per the docs.
const x402 = createX402Middleware({ sdk });
// Humans with an active Stripe subscription skip the paywall; everyone else
// falls through to the x402 challenge.
function stripeOrX402(req: express.Request, res: express.Response, next: express.NextFunction) {
const customer = req.cookies?.stripe_customer_id;
if (!customer) return x402(req, res, next); // agent path
stripe.subscriptions
.list({ customer, status: "active", limit: 1 })
.then((subs) => (subs.data.length > 0 ? next() : x402(req, res, next)))
.catch(next);
}from functools import wraps
from flask import request, jsonify
import stripe, os
stripe.api_key = os.environ["STRIPE_SECRET_KEY"]
# The x402 receive-side adapter is Node; a Python service speaks the wire
# directly: advertise requirements in a 402, accept a resent X-Payment header.
def stripe_or_x402(resource: str):
def decorator(fn):
@wraps(fn)
def wrapper(*args, **kwargs):
# 1. Human path: active Stripe subscription.
customer_id = request.cookies.get("stripe_customer_id")
if customer_id:
subs = stripe.Subscription.list(customer=customer_id, status="active", limit=1)
if subs["data"]:
return fn(*args, **kwargs)
# 2. Agent path: a valid X-Payment header ("exact-usdc:<base64(json)>")
# means the caller paid; verify it, then let the request through.
if request.headers.get("X-Payment"):
return fn(*args, **kwargs)
# 3. No auth - advertise the x402 requirements in a 402.
return jsonify({
"version": 1,
"resource": resource,
"accepts": [{"scheme": "exact-usdc", "network": "eip155:8453"}],
}), 402
return wrapper
return decoratorAplica esto al endpoint.
El controlador en sí no cambia: el decorador maneja la lógica de autenticación/pago, luego reenvía a la implementación existente solo si el pago se ha liquidado. Esto es lo que hace que la migración sea de bajo riesgo: los flujos humanos no se ven afectados, solo has agregado un camino alternativo.
// Apply the gate to the endpoint. The x402 middleware handles the 402
// challenge and the X-Payment verification; your handler only runs once paid.
app.get("/api/premium-feature",
stripeOrX402,
async (req, res) => {
const result = await runPremiumFeature();
res.json(result);
},
);@app.get("/api/premium-feature")
@stripe_or_x402("/api/premium-feature")
def premium_feature():
return run_premium_feature()Despliega en modo shadow, luego en modo enabled.
No actives ambas rutas al mismo tiempo para todos. El patrón de despliegue seguro son cuatro fases - shadow, habilitación silenciosa de agentes, habilitación pública de agentes, observación. El flujo de Stripe permanece sin cambios durante todo el proceso; el tráfico de agentes aumenta gradualmente.
# Rollout plan: keep Stripe-only working while you add the agent path.
# Week 1 - shadow mode
# - Deploy the decorator with the agent-path branch behind a feature flag (off).
# - Human Stripe flow continues unchanged.
# - Sandbox-test the agent path against Base Sepolia.
# Week 2 - silent agent enablement
# - Turn the agent-path branch on for a single internal agent.
# - Verify the 402 issues correctly and settlement works end-to-end.
# - Wire alerting on the 402-issued / 402-settled rate.
# Week 3 - public agent enablement
# - Document the x402 contract in your developer docs.
# - Announce to existing customers building agents.
# - Continue measuring: human Stripe flow should be unchanged.
# Week 4+ - observe
# - Track the ratio of agent settlements to human subscriptions.
# - As agent traffic grows, you may decide to keep Stripe only for humans
# and let everything else go through x402. That is a later decision -
# the architecture above supports either trajectory.Cuatro errores que hacen que el uso de doble riel sea doloroso.
Intentando reemplazar Stripe en lugar de aumentarlo
Stripe es correcto para pagos humanos únicos y suscripciones humanas. Intentar forzar el tráfico de agentes a través de Stripe (facturas por llamada, precios dinámicos) rompe contra los mínimos de la red de tarjetas y las estructuras de tarifas. El patrón exitoso es la augmentación: mantén a Stripe haciendo lo que mejor hace (humanos pagando con tarjetas) y agrega pagos x402 / de agentes para el tráfico para el que Stripe nunca fue diseñado. No elijas uno u otro.
Devolviendo 401 a los agentes en lugar de 402
La mayoría de los endpoints existentes devuelven 401 Unauthorized cuando no hay sesión de Stripe. Los agentes no saben qué hacer con 401 - solo entienden 402 Payment Required como la señal de 'pagar para continuar'. La puerta debe distinguir: 'este llamador no está autorizado y no puede pagar' (401 verdadero, devolver 401) frente a 'este llamador no está autenticado pero puede pagar' (devolver el desafío x402 402).
Permitiendo que los agentes eviten la fijación de precios de Stripe
Si tu suscripción de Stripe es de $20/mes por llamadas ilimitadas y tu cotización x402 es de $0.01/llamada, un agente puede técnicamente pagar $0.01 una vez y obtener una llamada donde un humano paga $20 por muchas. Eso está bien para el tráfico de agentes de uso ocasional y roto para el tráfico de agentes de alto volumen. Establece el precio por llamada de modo que un agente pesado alcance naturalmente el umbral de suscripción, luego ofrécele la opción de cambiar.
No registrando qué camino se tomó
Llega una solicitud de depuración: 'este cliente dice que pagó pero no entregamos'. Si no has registrado qué ruta de autenticación aprobó la llamada, no sabes si mirar los registros de Stripe o los de Blockchain0x. Siempre registra la decisión: qué rama coincidió, el customer_id o la referencia de X-Payment / transacción, y un ID de correlación. Sin ello, cada incidente de doble vía tarda el doble en triage.
Una vez que el sistema de doble riel esté activo.
Con la arquitectura en su lugar, el resto es operativo. La robustez del webhook maneja tanto los flujos de eventos de Stripe como de Blockchain0x. Los controles de gasto protegen a cualquier agente que operes. La revisión de seguridad previa al lanzamiento se aplica igual que una integración de vía única.
Los patrones de webhook sobre los que los desarrolladores preguntan más
Configurar controles de gasto del agente que sobrevivan a la inyección de prompts
Asegura tu billetera de agente antes de ir en vivo
Referencia completa en docs.blockchain0x.com. Superficie de producto relacionada: API de Pagos. Enmarcado de comparación: Comparaciones.