Neuronto Payments

npx add-mcp 'https://pay.neuronto.com/mcp'

Neuronto Payments: referencia para desarrolladores

URL base: https://pay.neuronto.com. OpenAPI 3.1 en /openapi.json. Guía para agentes en /llms.txt.

Qué es esto

Un facilitador de x402. x402 revive el 402 Payment Required de HTTP: un servidor responde a una solicitud no pagada con 402 y términos legibles por máquina, el cliente firma un pago en stablecoin, y un facilitador verifica la firma y liquida la transferencia en cadena. Este origen es ese facilitador. No retiene fondos: una liquidación mueve USDC del pagador a la dirección anunciada del comerciante en una sola transacción que el pagador firmó; el facilitador la transmite y paga el gas.

Endpoints

Método y ruta	Qué hace
GET /health	Comprobación de actividad. 200 mientras acepta tráfico.
GET /supported	Cada (x402Version, scheme, network) activo en este momento, las direcciones de firmante que pagan el gas, y datos por red (activo, nombre y versión EIP-712). Una red se retira aquí primero cuando no puede liquidar.
GET /verify, GET /settle	Sugerencias autodescriptivas que nombran el cuerpo esperado.
POST /verify	Verifica un pago firmado contra sus requisitos. No mueve nada. Gratis.
POST /settle	Liquida en cadena. Idempotente por cuerpo. Cabecera Idempotency-Key opcional.
GET /discovery/resources	Catálogo de recursos pagados a través de este facilitador: términos, método, y formas de entrada y salida donde el comerciante las publicó (extensión bazaar). limit, offset, network.
GET /discovery/stats	Estadísticas de liquidación y catálogo.
GET /status.json	Disponibilidad observada desde contadores de sondeo (límite inferior de Wilson, retenido por debajo de cinco sondeos), estado de la red, estado del filtrado de direcciones, y recuentos de liquidación. /status es lo mismo que una página.
GET /echo	Un comerciante en vivo para probar un cliente: responde 402, y un pago se reembolsa íntegramente en la misma solicitud. /echo/status indica si está sirviendo.
POST /mcp	Servidor MCP para agentes: facilitator_status, settlement_price, find_paid_resource, integration_snippet. Sin clave. GET y DELETE responden 405, nunca 404.
GET /integrate	El camino más corto desde cero hasta una ruta pagada, en cuatro frameworks.
GET /pricing	El precio de una liquidación, como JSON; /pricing.md como Markdown.
GET /.well-known/ard.json	Manifiesto de Descubrimiento de Recursos Agéntico para esta API.

Aceptar pagos

Apunta cualquier SDK de servidor x402 a este facilitador y anuncia una cartera que controles. Lo mismo con cada framework, y ejemplos ejecutables, está en /integrate. Python (FastAPI):

from x402.http import FacilitatorConfig, HTTPFacilitatorClient, PaymentOption
from x402.http.middleware.fastapi import PaymentMiddlewareASGI
from x402.http.types import RouteConfig
from x402.mechanisms.evm.exact import ExactEvmServerScheme
from x402.server import x402ResourceServer

facilitator = HTTPFacilitatorClient(FacilitatorConfig(url="https://pay.neuronto.com"))
server = x402ResourceServer(facilitator).register("eip155:8453", ExactEvmServerScheme())
routes = {"GET /premium": RouteConfig(
    accepts=[PaymentOption(scheme="exact", price="$0.01", network="eip155:8453", pay_to="0xYourWallet")],
    description="One premium answer")}
app.add_middleware(PaymentMiddlewareASGI, routes=routes, server=server)

TypeScript (Express): new HTTPFacilitatorClient({ url: "https://pay.neuronto.com" }) en lugar de cualquier otro facilitador. Nada más de los SDKs cambia. Base (eip155:8453) está en vivo. Para probarlo primero en Base Sepolia (eip155:84532), donde las liquidaciones son gratuitas y el USDC viene de un grifo, comprueba que /supported lo lista: el objeto networks allí marca cada red como available o no.

Pagar por cosas

Cualquier cliente x402 funciona sin cambios: nunca habla con el facilitador, solo con el servidor que respondió 402. Probar un cliente contra un 402 en vivo necesita un comerciante, y este origen ejecuta uno:

curl -i https://pay.neuronto.com/echo          # 402 with terms, then pay it with any x402 client

/echo cobra $0.001 en Base y lo devuelve directamente en la misma solicitud; el gas corre de nuestra cuenta. Está limitado por dirección y por día, y /echo/status indica si está sirviendo ahora mismo. Nada de esto es especial para este facilitador: es un recurso x402 ordinario que resulta que reembolsa.

Formas de solicitud y respuesta

POST /verify y POST /settle aceptan:

{"x402Version": 2, "paymentPayload": {...}, "paymentRequirements": {...}}

paymentPayload es la carga firmada del cliente exactamente como se envió en PAYMENT-SIGNATURE (decodificada); paymentRequirements es la opción que el servidor anunció y el cliente aceptó. Verificar responde {"isValid": true, "payer": "0x..."} o {"isValid": false, "invalidReason": "...", "invalidMessage": "..."}. Liquidar responde {"success": true, "transaction": "0x...", "network": "eip155:8453", "payer": "0x...", "amount": "10000"} o {"success": false, "errorReason": "...", "errorMessage": "...", "transaction": "", "network": "...", "payer": "..."}. Ambos mantienen la forma x402 en cada código de estado, porque los SDKs de x402 analizan el cuerpo independientemente.

Las razones sobre las que un pagador puede actuar comienzan con invalid_ (una firma incorrecta, un nonce usado, una ventana expirada, un saldo insuficiente). Las razones que son del facilitador (transaction_failed, service_unavailable) nunca cobran a nadie y llegan al operador. Una más: sanctioned_address significa que la dirección que paga, recibe o del comerciante aparece en la lista pública de sanciones contra la que este facilitador filtra; se rechaza antes de cualquier llamada en cadena, así que no se cobra nada y no se crea ninguna transacción. La lista y su antigüedad se publican en /status.

Semántica de liquidación

• Una vez por cuerpo. El JSON canónico de la solicitud es la identidad de la liquidación. El cuerpo idéntico se liquida una vez; reenviarlo devuelve el resultado registrado con Idempotency-Replayed: true.
• Idempotency-Key (opcional) se vincula al primer cuerpo con el que se envía; la misma clave con un cuerpo diferente se rechaza con 422.
• Pendiente. Una liquidación responde en unos 25 segundos o devuelve errorReason: "settlement_pending" con el hash de la transacción si se transmitió. Continúa en segundo plano. Reenvía el cuerpo idéntico para consultar; un resultado pendiente nunca se almacena en caché, uno final sí.
• Orden. Las liquidaciones en una red se procesan una a la vez, en el orden recibido.
• Simulación antes de la transmisión. La transferencia se simula de nuevo inmediatamente antes de enviarse, así que un pagador que vació su cartera después de la verificación falla limpiamente y sin coste de gas.
• Servir después de liquidar. Entrega el recurso pagado después de success: true, no después de verificar: la verificación prueba que el pago puede liquidarse, la liquidación prueba que se liquidó.

Errores

/verify y /settle mantienen la forma x402. Todo lo demás, incluidas rutas desconocidas, responde con detalles de problema RFC 9457:

{"type": "https://pay.neuronto.com/developers#not-found", "title": "Not Found", "status": 404, "detail": "No resource is served at GET /no-such-path."}

not-found: no hay ruta en esa dirección; no existe el prefijo /v1/. bad-request: el cuerpo no es JSON; en /verify y /settle esto llega como invalid_payload. payload-too-large: cuerpos de más de 65536 bytes. too-many-requests: ver límites de tasa. unprocessable-content: un Idempotency-Key reutilizado con un cuerpo diferente. internal-server-error: reintenta con retroceso; la respuesta no lleva detalles internos por diseño.

Límites de tasa

Por dirección de cliente, tres cubos, para que una liquidación no pueda privar de lecturas a cada llamada pagada: settle 50/s (ráfaga 100), payments-read ({/verify, /supported, /health}) 30/s (ráfaga 60), discovery (todo lo demás) 10/s (ráfaga 20). Una negativa es un problema 429 con Retry-After; cada respuesta nombra su cubo en RateLimit-Policy.

Redes

Red	CAIP-2	nombre v1	Activo	Testnet
Base Sepolia	eip155:84532	base-sepolia	USDC 0x036CbD53842c5426634e7929541eC2318f3dCF7e	sí
Base	eip155:8453	base	USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913	no

El dominio EIP-712 sobre el que firma un pagador difiere por red: USDC en Base es USD Coin versión 2; USDC en Base Sepolia es USDC versión 2. /supported lleva ambos para que un servidor nunca tenga que recordarlos.

Versionado

Por el campo x402Version en el cuerpo: 2 usa redes CAIP-2 (eip155:8453), 1 usa nombres cortos (base). Ambos se sirven desde las mismas rutas. Un tipo de pago se retira desapareciendo de /supported antes de que los endpoints dejen de aceptarlo.