Checkout para agentes

Principio de confirmación

Un agente puede buscar y comprobar disponibilidad sin autorización de compra. Antes de pagar debe mostrar el quote activo: artículos, cantidades, dirección, total Shopify, total USDC, destinatario y vencimiento. Sólo después de una confirmación inequívoca puede llamar pay_and_place_order con userConfirmed: true.

Si la persona cambia artículo, cantidad, dirección o presupuesto, o expresa duda, el agente no paga. Crea un quote nuevo y vuelve a presentar el resumen.

Secuencia recomendada

1. search_catalog para encontrar variantes.
2. check_availability para la cantidad que se desea comprar.
3. create_quote con dirección y confirmación de creación del quote.
4. Presentar el resultado y pedir confirmación de pago.
5. pay_and_place_order para recibir el endpoint x402.
6. La wallet hace el primer POST, lee el desafío 402, valida sus límites y firma localmente sólo si lo acepta.
7. Reintenta el POST con x402 y conserva quoteId para seguimiento. Envía un X-Request-Id propio (un token opaco de 8 a 128 caracteres) en cada llamada: Setareh lo devuelve y lo usa para correlacionar sus logs, lo que acelera cualquier revisión.
8. get_order_status para comunicar el resultado sólo cuando la orden fue creada, o para detectar payment_unknown o manual_review.

Controles mínimos de la wallet

La wallet no debe delegar estas decisiones en texto generado por un modelo:

• permitir únicamente stellar:testnet en este MVP;
• permitir únicamente el identificador canónico de USDC testnet;
• comparar payTo y monto con el quote que el usuario vio;
• limitar el gasto por pago con AGENT_MAX_USDC;
• rechazar un challenge sin payment-required válido;
• mantener la clave privada local y nunca añadirla a prompts, MCP o HTTP.

La implementación compara el requisito x402 con USDC_TESTNET_ADDRESS de @x402/stellar; no reemplaces esa comprobación por la etiqueta USDC ni por un identificador construido a mano. En x402 sobre Stellar, los pagos usan el token SEP-41 indicado por el desafío. Al fondear una cuenta con el activo clásico USDC, Stellar documenta el uso de un identificador CODE:ISSUER y de una trustline para recibirlo. x402 en Stellar, activos y trustlines

Cliente de referencia

El repositorio incluye un pagador local para testnet:

cd backend
npm.cmd run demo:pay -- <quoteId>

Ese cliente obtiene primero el desafío, verifica red, activo y límite, y sólo entonces configura el firmante Ed25519 para el reintento x402. Es una referencia de seguridad para integrar otra wallet; no es una custodia de producción.

Usar el entorno publicado

El cliente de referencia y cualquier wallet pueden apuntar al piloto publicado en lugar de una instancia local. En backend/agent.env:

SETAREH_API_URL=https://api.setareh.site
AGENT_MAX_USDC=5
# AGENT_STELLAR_PRIVATE_KEY se queda en este archivo local; nunca viaja al servidor.

El servidor nunca recibe la clave privada: la wallet firma el reintento x402 en local y Setareh sólo ve la prueba de pago que el facilitador liquida. Mantén AGENT_MAX_USDC igual o por debajo del tope del servidor (30 USDC por quote en el piloto) y usa únicamente fondos de stellar:testnet.

Resultado y lenguaje seguro

Di “orden creada” solamente si Setareh devuelve created y un identificador de orden Shopify. Si el resultado es payment_failed, out_of_stock o manual_review, explica el estado sin prometer una compra y deriva al proceso de recuperación.

Si el pago devuelve un error o un timeout, no firmes otro pago: consulta get_order_status. Si el estado es payment_unknown, el cobro puede haber ocurrido; Setareh rechaza cualquier nuevo pago de ese quote hasta conciliarlo. Explícalo así y no crees un quote nuevo para el mismo pedido.