La Agent Merchant API de Rozo elimina esa suposición. Una EOA de EVM puede registrarse como comercio con una sola firma de wallet; una vez aprobado el acceso, una segunda firma nueva autoriza una API key limitada a Orders para facturar y leer el estado de los pagos. Los fondos se liquidan como USDC en Base a la dirección firmante, y el agente puede consultar la API hasta que la liquidación llegue a payout_completed. Esta guía recorre todo el ciclo.
Qué obtiene realmente el agente
- Una cuenta de comercio ligada a su wallet: la primera firma válida la crea y las firmas repetidas reabren la misma cuenta; nunca se duplica.
- Liquidación fijada en el servidor a USDC en Base en la dirección firmante. Ninguna llamada a la API puede redirigir el destino del dinero.
- Una API key limitada a Orders: bajo el contrato actual puede crear facturas y leer el estado de pagos de su cuenta. No puede emitir credenciales Admin, gestionar la configuración de la cuenta ni cambiar la liquidación.
- Un enlace de pago por cada factura, que el agente comparte con el cliente. Para los comercios EVM de esta alpha, la liquidación se entrega como USDC en Base.
El ciclo de cinco pasos
- Pide un challenge: GET /account-nonce?chain=evm&address=$ADDRESS&intent=merchant_onboard. El servidor devuelve el mensaje exacto a firmar; los nonce anónimos se rechazan.
- Firma localmente y regístrate: POST /account-onboard con la dirección, la firma y el nonce. La clave privada nunca sale del entorno del agente.
- Solicita acceso y emite una credencial limitada: llama a POST /account-credentials/request con la sesión de wallet y reenvía la misma solicitud como máximo unas pocas veces al día para consultar su estado. Una vez aprobado, firma un challenge nuevo de credential_issue y llama a POST /account-credentials con scope "orders". La credencial emitida tiene alcance Orders; las credenciales Orders no pueden crear claves Admin.
- Crea una factura: POST /payment-api con un orderId estable, un Idempotency-Key, la información a mostrar y el importe en USDC. No envíes destination. Tras un fallo de red, reintenta con el mismo orderId y la misma clave de idempotencia.
- Consulta el estado del pago: haz polling con la key Orders y el orderId estable hasta payout_completed. Trata el estado devuelto como autoritativo aunque falle la entrega del webhook o del email. Si la respuesta incluye el hash de la transacción de payout, puedes verificarlo además en Base.
El contrato completo legible por máquinas está en https://partners.rozo.ai/llms.txt: está escrito para pegarse directamente en un agente.
Por qué los permisos son deliberadamente estrechos
Dar una credencial de pagos a un agente autónomo es justo el lugar donde ser paranoico. La API está diseñada para que el radio de daño de una key filtrada sea pequeño:
- Las keys Orders no pueden acuñar otras keys ni cambiar la liquidación, y sus lecturas se limitan a su propia cuenta. Listar y revocar credenciales emitidas por wallet requiere una firma nueva y ligada a su propósito.
- Emitir credenciales exige una firma de wallet nueva: un token de sesión robado por sí solo no puede acuñar una key.
- Cada challenge es de un solo uso, con propósito fijo y con caducidad indicada por el servidor.
- La dirección de cobro es la dirección firmante, aplicada en el servidor. Una key Orders filtrada no puede cambiar la dirección de liquidación configurada, pero sí crear facturas no deseadas y exponer el estado de pagos: revócala de inmediato con una prueba de wallet nueva.
Cómo conseguir acceso (alpha)
El programa de credenciales funciona por invitación durante la alpha. Tras el registro, el agente llama a POST /account-credentials/request y reenvía la misma solicitud como máximo unas pocas veces al día para consultar su estado. La aprobación es una decisión humana del lado de Rozo, pero no hace falta email ni mensaje directo. El ciclo de credenciales y facturación soporta actualmente EOAs de EVM con liquidación en USDC en Base. Las EOAs de Solana y Stellar pueden registrarse y liquidar USDC en la cadena de su dirección firmante, pero quedan fuera de este ciclo de credenciales.
Las wallets de contrato de EVM no están soportadas en esta alpha, y las cuentas solo-wallet no tienen vía de recuperación: si se pierde la clave firmante, Rozo no puede recuperar el comercio ni transferir la propiedad manualmente.
Empieza en https://partners.rozo.ai/agent.