Coste total por agente

Un agente gasta a través de Burnbound, pero a menudo también por fuera: una wallet que Burnbound no gestiona, una tarjeta de Stripe Issuing que no está enlazada a ningún agente, los tokens del modelo que consume. Esta página explica cómo Burnbound pone todo eso junto a cada agente: el gasto gestionado y el observado, el coste de tokens de Anthropic y OpenAI, los centros de coste y el exporte contable del mes.

¿Qué incluye el coste total de un agente?

Tres partes, que siempre se muestran por separado y luego se suman:

El gasto observado y el coste de tokens son solo visibilidad. Nunca cuentan para un tope, una regla, un mandato ni el plan, nunca se convierten en una intención de pago y Burnbound nunca los bloquea. Añadir gasto observado no cambia ninguna decisión de authorize. El gasto gestionado se explica en Conceptos.

La API da las tres partes de un mes UTC: GET /v1/agents/:agentId/total-cost?month=YYYY-MM, para cualquier persona con sesión en la organización. Devuelve managed, observed (por fuente) y tokens (por proveedor y modelo), cada una con testSpendUsd, la parte que es dinero de prueba, y totalUsd, la suma (con el dinero de prueba incluido). Si la retención de tu plan recorta el mes, visibleFrom indica desde cuándo cuenta.

¿Qué es el gasto observado?

Gasto que Burnbound no autorizó pero puede leer. Llega desde fuentes:

Cada movimiento se guarda una sola vez por organización, con el agente al que pertenece (o ninguno) y el centro de coste que tenía ese agente al guardarse. Quitar una fuente conserva el gasto ya guardado. Cualquier rol de la organización puede leerlo: GET /v1/observed-connectors lista las fuentes y GET /v1/observed-spend los movimientos, del más nuevo al más viejo (filtros agentId, source, from y to en YYYY-MM-DD, limit de 1 a 500, 100 por defecto; la página siguiente con before igual a next).

¿Qué wallets puede observar Burnbound?

Cualquier dirección pública en las redes que conoce Burnbound: Base, Tempo, Base Sepolia y Moderato (la red de pruebas de Tempo). Burnbound solo la lee. No hay clave, no se firma nada y nunca se te pide nada.

• Qué lee. Las transferencias salientes del activo de la red: USDC en Base y USDC.e en Tempo. Una transferencia hacia la dirección, a sí misma o de cero no es gasto. En Tempo, la comisión que se paga al fee manager no cuenta.
• Sin historial. Burnbound empieza en el primer bloque que su escaneo aún no había leído cuando ve la dirección por primera vez, y lee de ahí en adelante. Las transferencias anteriores al alta no aparecen nunca.
• Una dirección, una fuente. La misma dirección dos veces en la misma red es connector_exists (409). La dirección de una wallet que tu organización ya gestiona en Burnbound es address_already_managed (409): sus pagos ya son gasto gestionado.
• Redes de prueba. Las transferencias en Base Sepolia y Moderato son dinero de prueba y se muestran aparte.
• Errores. Si falla el RPC de la red, las fuentes de esa red muestran Error con un código, nunca un mensaje, y la siguiente pasada sigue donde se paró el escaneo.

Owners y admins añaden y quitan direcciones en Organización → Gasto observado, con un agente si quieren. Cada cambio queda auditado (observed_connector.created, observed_connector.deleted).

¿Cómo observo las tarjetas de Issuing?

Las envía tu gateway de acciones. Se ejecuta con tu clave de Stripe, así que Burnbound nunca lee Stripe por su cuenta. Pon GATEWAY_SYNC_ISSUING=1 y dale a la clave restringida del gateway dos permisos más: Issuing Transactions: Lectura e Issuing Cards: Lectura. La sincronización nunca escribe en Stripe. Cómo poner en marcha el gateway está en Pon en marcha el gateway en 5 minutos.

• Qué tarjetas. Una tarjeta con burnbound_agent_id en sus metadatos está enlazada a Burnbound: sus autorizaciones ya pasan por el webhook de tarjetas y sus capturas no se envían nunca. Las capturas de cualquier otra tarjeta son gasto observado.
• Qué agente. Pon burnbound_observe_agent_id en los metadatos de una tarjeta para indicar a qué agente pertenece su gasto. Sin él, o con un id que no es de un agente de tu organización, las capturas se guardan sin agente.
• Qué se envía. Solo capturas. Los reembolsos de Issuing no se envían. Una captura en una moneda sin tasa en Burnbound se deja fuera y queda en el log.
• Cuándo. Cada GATEWAY_SYNC_INTERVAL_SECONDS (300 por defecto, de 60 a 86400). La primera pasada lee los últimos 7 días y las siguientes empiezan en la captura más nueva leída. Una pasada lee como mucho 5000 capturas, y una ventana más larga la terminan las pasadas siguientes. Burnbound guarda cada captura una vez, así que un reinicio que vuelve a leer no hace daño.

La fuente aparece como Gateway de acciones (Issuing) en Organización → Gasto observado.

¿Cómo envío mi propio gasto?

Con una clave de organización, POST /v1/observed-spend/batch guarda el gasto que tú mismo registras. Un lote admite hasta 500 filas y 1 MB. Es todo o nada: una fila mala rechaza el lote entero y no se guarda nada. Es idempotente por source y externalId: una fila repetida cuenta como duplicada y no cambia, salvo una fila de tokens (llm_anthropic, llm_openai) con otros valores, que reemplaza a la guardada.

{
  "rows": [
    {
      "source": "stripe_issuing",
      "externalId": "ipi_…",
      "occurredAt": "2026-11-03T10:00:00Z",
      "amountMinor": 1299,
      "currency": "EUR",
      "agentId": "…",
      "counterparty": "Comercio de ejemplo",
      "description": "Comida del equipo",
      "test": false
    }
  ]
}

Los importes se pasan a USD con las mismas tasas que usa Burnbound para tarjetas y reembolsos, redondeando hacia arriba. Una moneda sin tasa se rechaza, nunca se estima.

La respuesta es 200 con inserted, duplicates, replaced (filas de tokens que corrigió un proveedor) y connectorId. Los rechazos son:

¿Qué planes lo incluyen?

El gasto observado y el coste de tokens están en Team y Business. En Free, añadir una dirección, guardar un lote y crear o mover asignaciones de claves responden 403 plan_limit_reached con limit: "observed_spend".

El límite solo cierra las escrituras. Lo ya guardado se sigue pudiendo leer en cualquier plan, y lo que ya existe sigue funcionando: una dirección registrada antes de pasar a Free se sigue leyendo. Las sincronizaciones de Issuing y de tokens del gateway no: sus lotes son escrituras y reciben 403 plan_limit_reached. Los centros de coste están en todos los planes; los informes que desglosan el gasto por centro necesitan reports (Team y Business).

¿Cómo lee Burnbound el coste de tokens?

Lo lee tu gateway de acciones con la clave de administración de cada proveedor y lo envía a Burnbound como gasto observado. Las claves de administración se quedan en el gateway y solo van a su proveedor. Burnbound recibe importes por día, clave, workspace o proyecto y modelo: nunca una clave ni un prompt.

GATEWAY_SYNC_LLM=anthropic,openai
ANTHROPIC_ADMIN_KEY_FILE=/run/secrets/anthropic_admin_key
OPENAI_ADMIN_KEY_FILE=/run/secrets/openai_admin_key

• Claves. En Anthropic, una Admin API key (sk-ant-admin…), que crea un admin de la org en la Claude Console. En OpenAI, una clave de administración (sk-admin-…), que crea un owner en los ajustes de la organización. Una clave de API normal no puede leer el coste y el gateway la rechaza al arrancar. ANTHROPIC_ADMIN_KEY y OPENAI_ADMIN_KEY también funcionan, con un aviso: un archivo secreto deja la clave fuera de la lista de procesos y de los logs de la plataforma.
• Guárdalas bien. Una clave de administración puede hacer más que leer el coste en su proveedor. Tenla solo en el gateway y rótala si se filtran los secretos del gateway.
• Qué lee. El coste de cada día UTC cerrado, por clave de API, workspace de Anthropic o proyecto de OpenAI, y modelo: una fila por día, agrupación y modelo. Los importes de menos de un céntimo se guardan hasta el microdólar.
• Tokens. El coste de OpenAI viene con los tokens de entrada y de salida. El de Anthropic no, así que sus filas llevan el importe y el modelo, con 0 tokens.
• Sin clave de Stripe. Un gateway puede ejecutar solo esta sincronización.

El coste de tokens es solo visibilidad. Burnbound no hace de proxy ni limita ni bloquea las llamadas al modelo.

¿Cómo asigno una clave a un agente?

En Organización → Coste de tokens, elige el proveedor, qué asignas y su id, y el agente:

Escribe el id que muestra el proveedor en su consola (apikey_…, wrkspc_…, key_…, proj_…), nunca la clave secreta. Un valor que parece una clave (sk-…) se rechaza con invalid_llm_mapping y no se guarda nunca.

• Qué agente recibe una fila. Primero cuenta la asignación de su clave y después la de su workspace o proyecto. Sin ninguna, el coste es de la organización, sin agente.
• Quién. Owners y admins crean, mueven y quitan asignaciones; cualquiera con sesión en la organización las ve, viewers incluidos. Hasta 500 por organización. Cada cambio queda auditado (llm_cost_mapping.created, llm_cost_mapping.updated, llm_cost_mapping.deleted).
• Cuándo se aplica. El gateway lee las asignaciones, firmado, al empezar cada pasada. La siguiente lectura apunta el coste de ese id al agente.

Las mismas asignaciones están en la API en /v1/observed-spend/llm-mappings (GET, POST, PATCH y DELETE).

¿Qué pasa cuando un proveedor corrige un día?

Los proveedores revisan su coste a posteriori, así que el gateway vuelve a leer días:

• Primera pasada: los últimos 7 días. Después, cada pasada lee como mucho 14 días nuevos, más los que relee.
• En cada pasada: los 2 últimos días enviados.
• Cada 6 horas: todos los días que el proveedor aún puede revisar: el mes en curso y, hasta el día 8, el anterior, sin ir más atrás del primer día que leyó el gateway.
• Anthropic: un día que Anthropic aún no ha terminado de contar se lee más tarde.

Un importe corregido reemplaza su fila en Burnbound. Solo se reemplazan las filas de tokens; las de Issuing y las de cadena solo se insertan. La fila reemplazada vuelve a sellar su centro de coste, y la auditoría registra observed_spend.corrected con el importe y el agente que tenía antes. Una fila que el proveedor deja de devolver no se borra.

Mover o quitar una asignación usa esas mismas relecturas. En unas horas, el coste de este mes apuntado a esa asignación pasa al agente nuevo (hasta el día 8, también el del mes anterior). Si la quitaste, el coste pasa al agente de su workspace o proyecto, si tiene asignación, o a la organización. El coste más antiguo conserva el agente que tenía.

¿Y si falla la sincronización de tokens?

La lectura de cada proveedor aparece como su propia fuente en Organización → Gasto observado, Gateway de acciones (tokens de Anthropic) o Gateway de acciones (tokens de OpenAI), con su estado y su última lectura. Un error es un código, nunca el mensaje del proveedor:

Un error con un proveedor nunca para al otro ni a los reembolsos. Antes de informar de un 429, el gateway espera lo que pide (su retry-after, como mucho un minuto, tres veces).

¿Qué es un centro de coste?

Una etiqueta en cada agente que dice a qué presupuesto pertenece su gasto, como Marketing o CC-1001. No hay lista que preparar: es texto libre por organización, de 1 a 64 caracteres, que empieza por una letra o una cifra y sigue con letras sin tilde, cifras, espacios o . _ / -. Los espacios de los extremos se recortan; vaciarlo en el panel (o null en la API) lo quita.

• Quién lo cambia. Owners y admins, en el panel del agente, con los centros ya en uso como sugerencias. El resto lo ve en solo lectura. Cada cambio queda auditado (agent.cost_center_changed).
• Se sella. Cada pago se queda con el centro de coste que tenía su agente al reservarse, también los de tarjeta y los reembolsos. Cambiarlo nunca mueve los pagos pasados. Las filas observadas y las de tokens se quedan con el centro que tenía el agente al guardarse.
• En el informe mensual. Por centro de coste reparte el gasto por el centro sellado en cada pago. Los bloqueos y las aprobaciones, que solo conocen el agente, van al centro que tiene hoy el agente. payments.csv lleva una última columna cost_center.

En la API: PUT /v1/agents/:agentId/cost-center (un owner o admin con sesión; cualquier clave de API recibe 403) y GET /v1/org/cost-centers (los centros en uso, para cualquier rol con sesión).

¿Qué lleva el exporte contable?

Lo que se liquidó en un mes natural UTC, por centro de coste, raíl y moneda, con un total por centro: el archivo que finanzas lleva a su contabilidad. Se descarga desde Exporte contable en el informe mensual, o desde la API: GET /v1/reports/accounting.csv?month=YYYY-MM y GET /v1/reports/accounting?month=YYYY-MM (JSON).

• Cuenta la fecha de liquidación. Solo pagos en settled, por la hora a la que se liquidaron (UTC), no por la de reserva. Un pago reservado el día 31 a las 23:50 y liquidado pasada la medianoche es del mes siguiente.
• Solo gasto gestionado. El gasto observado y el coste de tokens no entran.
• El dinero de prueba, aparte. Las filas de prueba (test = true) van después de las reales y nunca suman a un total.

En el CSV van primero las filas de cada centro y después su fila de total (asset y amount_original vacíos). El archivo se llama burnbound-accounting-YYYY-MM.csv y empieza con una marca de orden de bytes, salvo que añadas bom=0. El JSON da rows (cada una con test) y totals (solo dinero real). Sin month sale el mes en curso; un mes que aún no ha empezado es 400 invalid_month. Los dos se recortan a lo que muestra tu plan.

¿Dónde lo veo?

Allí donde aparecen, el gasto observado y el coste de tokens llevan la marca de solo visibilidad y se quedan fuera de los totales propios de Burnbound.