Documentación de TilcAI

TilcAI es infraestructura de comercio entre agentes: el asistente de una persona u organización consulta, cotiza y compra a un negocio con autoridad limitada, condiciones verificables y pagos sobre Stellar.

Recibe una intención de compra o reserva, obtiene del negocio una oferta con precio, disponibilidad y destino de cobro verificables, aplica identidad, límites y aprobación, coordina un pago por un riel soportado y vincula el resultado financiero con la orden y con la confirmación comercial. Se construye por etapas y los nombres pueden cambiar. El flujo de compra completo no está habilitado.

• Base disponible Un pago técnico de USDC de Avalanche Fuji a Stellar Testnet con CCTP, también sin gas para el comprador; un riel x402 con OpenZeppelin Relayer probado de forma aislada; un evaluador determinista de políticas y contratos compartidos versionados.
• En integración Conector MCP, cotizaciones y órdenes, aprobación por compra, unión de orden, pago y entrega, canal de WhatsApp y emisión de cuentas.
• Siguientes pasos Smart accounts con permisos limitados, presupuesto compartido entre agentes, tareas programadas y más rutas de CCTP.

Que un componente esté disponible no equivale a que el flujo de compra esté habilitado. Nada de esto ha sido auditado y nada opera con fondos reales. Cada capacidad, con su evidencia y quién la mantiene, está en el estado de construcción.

Qué construye TilcAI y qué es externo

El primer flujo apunta a un negocio, un servicio, un asistente, un usuario y un activo en stellar:testnet.

Una sola operación une al comprador y al negocio. Cada paso tiene un responsable, un estado y su propia evidencia: el pago nunca se confunde con la entrega.

1. Intención

   El comprador pide un producto o servicio, la cantidad y las condiciones. TilcAI estructura la intención y registra al principal autenticado.

   Estado

   Solicitud

   Evidencia

   Mensaje y principal autenticado

2. Oferta

   El negocio consulta su fuente de verdad y devuelve una cotización identificada, con vigencia, activo, importe, costes, disponibilidad y el destino de cobro (payTo) registrado. Si no puede garantizar stock o cupo, lo confirma antes de prometerlo.

   Estado

   Cotizada, o pendiente de confirmación

   Evidencia

   quoteId, versión, fuente y hora de la disponibilidad

3. Verificación

   TilcAI verifica la identidad del negocio, el destino de cobro, la versión de la oferta, los límites y la política. Un rechazo o una aprobación pendiente no inicia el pago. ALLOW es elegibilidad: no firma ni paga.

   Estado

   Evaluada

   Evidencia

   Decisión y código de motivo

4. Aprobación

   La persona revisa las condiciones exactas en una superficie confiable y las aprueba. La aprobación compromete importe, activo, red, destinatario, quoteId, vencimiento y orderId. Un «sí» escrito en un chat no sustituye la autorización.

   Estado

   Aprobada

   Evidencia

   Aprobación vinculada a la orden

5. Pago

   El router elige una sola ruta, el pago directo en Stellar con x402 o USDC desde otra red con CCTP. Cada intento lleva una clave de idempotencia.

   Estado

   Preparada, enviada

   Evidencia

   paymentAttemptId y ruta elegida

6. Conciliación

   TilcAI comprueba la evidencia en la cadena y relaciona orderId, quoteId, paymentAttemptId, hash de origen, atestación y hash de destino. Un tiempo agotado es UNCERTAIN hasta conciliar: no es permiso para repetir el pago.

   Estado

   Liquidada

   Evidencia

   Recibo financiero con enlaces de testnet

7. Cumplimiento

   El negocio confirma por separado la reserva, el retiro o la entrega. Comprador y negocio ven el mismo estado de la orden, cada uno con su recibo.

   Estado

   Cerrada o en seguimiento

   Evidencia

   Confirmación del negocio, distinta del recibo de pago

Contrato común mínimo

Los canales, la API y los rieles comparten los mismos identificadores:

• principalId
• agentId
• businessId
• serviceId
• quoteId
• orderId
• paymentAttemptId

A ellos se suman los estados de comercio, pago y presupuesto de tilcai-shared-v1, un Idempotency-Key en cada escritura, montos en unidades atómicas, una red inequívoca y un payTo versionado. Los contratos compartidos son una propuesta: el equipo debe revisarlos antes de fijarlos como API definitiva.

Pagado no significa entregado. Si la entrega falla después del pago, el resultado es una excepción comercial visible, no una conversión automática. La cancelación y la devolución necesitan sus propias reglas y todavía no existen.

Una solicitud recorre tres planos que permanecen separados, de modo que puede avanzar en el primero sin tener permisos en el tercero. El modelo de lenguaje ayuda con la tarea; la infraestructura decide qué acciones pueden ejecutarse y bajo qué condiciones.

Las órdenes, los mandatos y los estados se guardan en almacenamiento durable: el historial de un chat no es un registro de compras. Los módulos son responsabilidades lógicas, no un servicio por caja.

El negocio conserva la autoridad sobre sus servicios, precios, disponibilidad, destino de cobro y confirmación de entrega. TilcAI no inventa stock, descuentos ni confirmaciones.

Cuatro caminos de integración

Son propuestas de incorporación, no un producto lanzado. Todavía no hay un portal de comercio, un catálogo real conectado ni un agente vendedor operativo; se prueban primero con un negocio piloto acotado, en testnet. Para empezar no se necesita un agente de IA ni un sitio web.

Qué conserva el negocio

• Capacidades explícitas. Cada negocio expone solo las operaciones que admite, por ejemplo consultar disponibilidad, retener un recurso o confirmar una orden. Los permisos las distinguen.
• Contexto desde la autenticación. Negocio, usuario y rol provienen de la sesión autenticada, nunca de un argumento libre propuesto por el modelo.
• Identidad de alcance limitado. Un negocio registra su operador, origen, claves y destino de cobro. Controlar una clave o un dominio no demuestra identidad legal ni calidad comercial.
• Cotizaciones firmadas. Una cotización vincula negocio, servicio, cantidad, precio total, red, activo, destinatario, vencimiento y un hash de las condiciones.

Un comprador acepta una cotización solo cuando:

1. la clave de firma la reconoce una fuente independiente (el alta del negocio, un registro aceptado o la configuración confiable del principal), nunca se toma de la propia cotización;
2. servicio, red, activo, monto y destinatario coinciden exactamente con los requisitos de pago, y la cotización no ha vencido;
3. la política, el presupuesto y la aprobación siguen permitiendo la operación.

Una firma protege las condiciones después de firmadas. No protege frente a una clave comprometida, un origen de phishing o una política mal configurada, y nunca concede autoridad de gasto.

Quién responde por el negocio

El agente vendedor es la interfaz operativa que atiende las solicitudes mediante capacidades autorizadas. Puede ser un servicio de reglas con un operador humano de respaldo (el modo recomendado para el piloto, porque es el más comprobable), un asistente gestionado por TilcAI o un agente propio de la empresa conectado por API. En todos los casos el modelo no fija por sí solo precio, stock, cobro ni autoridad.

La entrega la aporta el negocio. La orden la confirma y cumple el sistema propio del negocio, y esa evidencia se mantiene separada del recibo de pago. Publicar el perfil de un negocio requiere su aprobación; agregar un perfil o explorar un caso de uso no habilita ventas. Un negocio se presenta como habilitado solo cuando su flujo operativo ha sido verificado.

Hay tres puertas de entrada a la misma infraestructura. Todas terminan en los mismos servicios de identidad, oferta, política, autorización, orden, pago y recibos: el canal no es la autoridad financiera.

Herramientas MCP

MCP (Model Context Protocol) es la interfaz de herramientas para asistentes compatibles. TilcAI está diseñado para publicar un servidor MCP con operaciones específicas, autenticado según la especificación de autorización de MCP. Todavía no hay un servidor MCP expuesto. Los nombres siguientes son el contrato diseñado en tilcai-core, no un paquete publicado.

El modelo trabaja con identificadores de cotización, intención y orden. No existe una herramienta irrestricta para enviar dinero a una dirección cualquiera. Precio, destinatario, cantidad, red y activo viajan como datos versionados; la conversación explica esos datos pero no los redefine.

• Conectar no es gastar. Conexión, acceso a datos y autoridad de compra son cosas distintas. Seleccionar un asistente o permitir una herramienta nunca concede permiso de gasto.
• Una skill es guía, no permiso. Explica cómo consultar, aclarar, preparar y comunicar estados. El servidor aplica las reglas aunque un agente ignore la skill.
• El soporte es por capacidad. El catálogo de clientes distingue lectura, cotización, preparación y ejecución. Soportar MCP no implica pagos autónomos. Cada cliente se prueba con su propia versión y autenticación.
• Estado hoy. Todos los clientes del catálogo están en preparación. Se publica una guía para un cliente solo después de probarlo, y ninguna guía pide una frase semilla, una clave privada ni un token.

Un pago es elegible solo cuando se cumplen a la vez cuatro condiciones. Una firma válida no basta para autorizarlo, y la reputación puede informar una decisión pero nunca se salta un límite.

1. una identidad reconocida y una oferta auténtica y vigente;
2. una intención vinculada a una orden y un mandato aplicable;
3. presupuesto disponible y retenido;
4. aprobación exacta o una delegación verificable.

Decisiones y estados son cosas distintas

El motor de políticas devuelve ALLOW, DENY o REQUIRE_APPROVAL. El prototipo actual devuelve ALLOW o DENY; la aprobación humana forma parte del flujo de autorización. Una orden mantiene estados de comercio, pago y presupuesto por separado, así que una orden pagada aún puede estar pendiente de entrega.

Dos formas de autorizar

• Aprobación por compra (primera ruta). La persona conecta una cuenta compatible y revisa servicio, monto, activo, red, destinatario y condiciones. La wallet firma una autorización compatible con el riel, que en x402 sobre Stellar es una entrada de autorización Soroban. Una firma de inicio de sesión o conectar la wallet no basta. Si cambian la oferta o la invocación, se exige una nueva aprobación.
• Delegación limitada (ruta objetivo). Una smart account Soroban de la persona acepta un firmante restringido dentro de un mandato: red y activo exactos, contratos permitidos, destinatarios, montos por operación y por periodo, proveedores, vigencia y revocación. Se habilita solo después de probar juntas la cuenta, el firmante y el riel.

Cuando algo falla

• Pago incierto. Un tiempo agotado después de enviar no es un fallo. Se mantiene la retención de presupuesto y se concilia el mismo intento antes de firmar de nuevo. Repetir una consulta puede ser seguro; repetir una ejecución financiera exige conocer el estado del intento anterior.
• Pago sin entrega. La orden no se marca como entregada. El problema se resuelve según las condiciones comerciales, y repetir la compra no es una solución automática.
• Revocación. Revocar un mandato bloquea nuevas firmas. No revierte un pago que ya se liquidó.
• Condiciones cambiadas. Un precio, proveedor o servicio distinto detiene la operación hasta una nueva aprobación. El agente no puede subir su propio límite ni aprobar su propia excepción.

TilcAI escoge una sola ruta para cada orden. El pago directo en Stellar y el pago entre redes con CCTP son alternativas, no dos cobros de la misma orden, y todavía no forman un checkout comercial integrado.

Ciclo de vida de un pago entre redes

Un pago avanza por estados guardados: un reintento retoma desde el último y nunca repite el burn.

1. AWAITING_BURNPago creado, a la espera del burn firmado
2. BURN_SUBMITTEDBurn enviado; su hash queda guardado
3. BURN_CONFIRMEDEl recibo y el evento coinciden con la cotización
4. ATTESTEDCircle atestó y el mensaje se verificó de nuevo
5. MINT_SUBMITTEDEl Relayer envió el mint
6. SETTLEDMint confirmado; USDC en destino y recibo de pago

• Un burn respalda un solo pago y un nonce de CCTP una sola liquidación.
• El mint es idempotente. Se reintenta sin riesgo, y nunca se crea un segundo burn para un pago existente.
• La firma compromete lo exacto. En el modo sin gas el Relayer solo puede enviar lo que el pagador firmó.
• La incertidumbre se concilia. Un burn no encontrado o una atestación que no coincide pasan a UNCERTAIN y no se emiten; nunca se marcan como fallidos sin evidencia.

Cobertura de redes

El laboratorio tilcai-cctp-engine modela ocho redes de prueba. El backend de TilcAI acredita un solo corredor completo.

• Avalanche FujiVerificado en TilcAI
• Ethereum SepoliaVerificado en TilcAI
• Arbitrum SepoliaVerificado en TilcAI
• Base SepoliaVerificado en TilcAI
• Arc TestnetLaboratorio
• Solana DevnetLaboratorio
• Sui TestnetLaboratorio
• Stellar TestnetDestino · USDC del negocio

«Laboratorio» significa código, matriz de rutas y verificación de contratos; falta la transferencia y la conciliación de punta a punta de cada ruta. Que Circle admita una red no la habilita en TilcAI: se habilita una por una, cuando supera su prueba. CCTP mueve USDC nativo: no convierte bolivianos ni otros tokens, y quien ya tiene USDC en Stellar no lo necesita.

El detalle técnico, los payloads y el contrato de errores del riel x402 están en la documentación del riel de pago del repositorio abierto tilcai-core.

La cuenta es de la persona o de la organización, no una «wallet del bot». El agente es software autorizado para pedir acciones; no es dueño de los fondos.

La emisión de cuentas está en preparación: hay plan, contratos base y puertos definidos. La API que emite cuentas, la recuperación probada y los despliegues siguen pendientes.

Crear una cuenta desde un chat

El chat solo inicia el proceso y muestra estados. Una pantalla web segura, ligada a una sesión corta, es la frontera para identidad, credenciales y firmas.

1. El canal genera un enlace de un solo uso, con expiración. No se envían semillas ni claves por el chat.
2. El navegador abre un origen HTTPS de TilcAI y la persona crea su credencial de propietario, preferentemente una passkey; si no, una clave propia o la conexión de una wallet existente.
3. TilcAI asocia la clave pública al principal autenticado y solicita la cuenta con una clave de idempotencia. Las credenciales técnicas se quedan en el servidor.
4. El proveedor de cuentas calcula la dirección y despliega la smart account; solo la marca activa al comprobar el despliegue en la cadena. El Relayer paga la comisión y no se convierte en dueño.
5. La persona ve su dirección, la red, el activo y cómo fondear. Crear una cuenta no la fondea.
6. Para comprar se prepara una aprobación exacta del dueño. La delegación posterior es opcional, limitada y revocable.

Cómo se fondea

TilcAI no acredita saldo por la captura de un QR ni por un aviso sin autenticar: un depósito se acredita solo con la confirmación verificable del proveedor.

Recuperación

Perder el teléfono, cambiar el número de WhatsApp y recuperar una cuenta son problemas distintos. El número de un chat identifica una conversación, no demuestra por sí solo la propiedad de los fondos, y nadie debería poder reasignar una cuenta porque controle ese número. El diseño de recuperación debe revisarse antes de usar fondos reales.

Lo que ocurre en el backend se registra como eventos con un orden que solo crece, llega firmado al sitio y se interpreta en español e inglés. Mirar no puede romper lo que se mira.

• El backend es la fuente de verdad. Anota cada evento con una posición que solo crece; el sitio guarda una copia reciente y nada más.
• El backend empuja. Puede vivir detrás de una red privada, así que quien inicia la conexión es él, con un envío firmado.
• Al menos una vez y en orden. Si el sitio estuvo caído, recibe después lo que se perdió; lo repetido se descarta por identificador.
• Monitorizar no rompe lo monitorizado. Emitir un evento nunca falla ni espera a la red.

Los avisos sirven para ver, no para decidir: un pago o un desembolso solo se da por liquidado cuando TilcAI comprobó la cadena por su cuenta.

Seguridad del canal

• Un secreto por dirección. Uno protege la escritura (del backend al sitio) y otro la lectura (de la persona al sitio). Ninguno llega al navegador.
• El envío caduca. La firma cubre la hora, y el sitio rechaza lo que tenga más de cinco minutos.
• Sin secretos en los eventos. Sí llevan direcciones públicas, saldos, montos y hashes, y por eso la lectura exige credencial.
• El navegador nunca habla con el backend ni conoce su dirección.

El recorrido completo está implementado y verificado en local contra servicios de testnet. La vista /es/monitor es una base funcional sin diseño final. Faltan el tablero, un almacén duradero en el sitio (hoy es memoria y no sirve con varias instancias) y apuntar el relayer real a TilcAI.

• El modelo propone; las reglas deciden. La salida del modelo nunca se acepta para precio, destinatario ni aprobación. Una condición que no se puede verificar bloquea la operación o pide revisión humana.
• El firmante es una frontera separada. Las claves quedan fuera del alcance del modelo y de los datos del negocio. Este sitio web no almacena claves privadas, tokens financieros ni mandatos de gasto.
• Dependencia del facilitador y del Relayer. La liquidación depende de un facilitador x402 y de un OpenZeppelin Relayer. Si no están disponibles, los pagos se detienen.
• Solo testnet. El backend rechaza cualquier entorno distinto de testnet, y testnet y mainnet tendrán configuración y habilitación separadas. No hay fondos reales.
• Laboratorio no es producto. Ocho redes modeladas no son ocho corredores comerciales: hoy cuatro están verificadas.
• Sin auditar. Nada de lo descrito aquí ha sido auditado.

Fuera del alcance por ahora: un marketplace de agentes, trading o DeFi, puentes de activos envueltos entre cadenas (el pago entre redes con CCTP, que retira y emite USDC nativo, sí está previsto y hoy están verificadas Avalanche Fuji, Ethereum Sepolia, Arbitrum Sepolia y Base Sepolia hacia Stellar), negociación libre de precios, compras a cualquier negocio sin adaptador, servicios regulados, conversión de bolivianos sin un proveedor verificado y autonomía ilimitada de los agentes.

Son extensiones previstas, no activas. Se añaden detrás de las mismas operaciones y estados.

• Extensión prevista A2A. Un estándar de comunicación entre agentes, con capacidades descritas mediante Agent Cards. Conectaría la solicitud del comprador con las capacidades del agente de la empresa. No sustituye inventario, mandato ni firma financiera. El primer flujo puede funcionar con MCP y una API comercial.
• Extensión prevista ERC-8004. Un estándar en borrador para registros de identidad, reputación y validación en Ethereum/EVM. No es un contrato nativo de Stellar ni garantiza confianza. TilcAI prevé una identidad operativa nativa en Stellar y, por separado, un adaptador para resolver un registro EVM. Consultar una identidad EVM nunca mueve fondos entre redes ni construye un bridge.
• Siguientes pasos Smart accounts, presupuesto compartido y tareas programadas. Consulta el estado de construcción.

Principal

La persona u organización que posee los fondos y otorga la autoridad.

Mandato

Autoridad delegada a un agente, con alcance, límites, periodo y revocación.

Cotización

Condiciones comerciales exactas de un negocio: servicio, precio, activo, red, destinatario y vencimiento.

Intención

La compra que una persona quiere hacer, vinculada a una cotización e inmutable una vez creada.

Orden

La operación comercial que vincula al principal, el negocio y la cotización, con estados propios.

MCP

Model Context Protocol: la interfaz de herramientas para asistentes compatibles.

A2A

Un estándar de comunicación entre agentes. Es una extensión prevista, no un requisito del primer flujo.

x402

Un protocolo de pago HTTP: un servidor responde 402 Payment Required con las condiciones de pago y el cliente paga para obtener el recurso.

Facilitador

El componente que verifica y presenta un pago x402. Aquí, un plugin que corre en un OpenZeppelin Relayer.

OpenZeppelin Relayer

Un servicio que envía transacciones con las redes, los firmantes y las políticas que se le configuran. Puede pagar la comisión de red sin convertirse en dueño de los fondos.

CCTP

Protocolo de Circle que mueve USDC nativo entre redes: lo quema en el origen, espera una atestación y lo emite en el destino.

Atestación

La firma de Circle (servicio Iris) que prueba que el burn ocurrió y permite emitir en el destino.

Soroban

La plataforma de contratos inteligentes de Stellar.

Smart account

Una cuenta programable cuyas reglas, firmantes y límites los define un contrato.

Idempotencia

Repetir una operación con la misma clave produce el mismo resultado y no la ejecuta dos veces.

Tenant

El espacio aislado de un negocio o integrador, con su identidad, sus cuotas y sus roles.

Vault

Contrato de TilcAI en Avalanche Fuji que ejecuta desembolsos sujetos a presupuesto, límite por pago y pausa.

Conciliación

Establecer el resultado real de un intento de pago, incluso cuando una llamada falló a mitad de camino.

Código de motivo

Una explicación legible por máquina de una decisión.

Esta página resume el contexto oficial del equipo, con corte al 8 y 9 de octubre de 2026, y el código de los repositorios. El código y sus pruebas determinan qué está implementado; una prueba en testnet acredita la ruta reproducida, no todas las rutas previstas.

• Del repositorio abierto tilcai-core: contratos compartidos, herramientas MCP, intención y mandato, riel de pago en testnet y reproducibilidad del riel.
• Referencias externas: OpenZeppelin Relayer, smart accounts en Stellar, redes y dominios de CCTP y herramientas de MCP.