>_ Documentación para developers

Construí pagos para agentes con Cardia.

La capa de pagos para agentes de IA, LATAM-first. Emití tarjetas, fondeá en pesos o con cripto (USDT vía Manteca), y autorizá cada compra con scope — todo por CLI o API.

Empezar

Overview

Cardia es una capa de pagos para agentes de IA, pensada para LATAM. Emite tarjetas virtuales (vía Pomelo), con fondeo en pesos a través de CVU y con cripto (USDT y otras stablecoins, vía Manteca).

El diferencial es la autorización con scope: permisos acotados por comercio, monto máximo y vigencia, operables por CLI. El agente no se autoriza a sí mismo — vos definís dónde, cuánto y hasta cuándo puede gastar.

El límite vive en la tarjeta, no en el prompt.

Tarjetas vía Pomelo

Emisión de tarjetas virtuales conectadas a la red de pagos.

Fondeo ARS + cripto

Saldo en pesos por CVU y carga con USDT vía Manteca (off-ramp cripto→pesos).

Scope por permiso

Comercio + monto máximo + vigencia, acotado y de un solo uso.

Operable por CLI y API

Mismo poder desde la terminal o desde tu backend.

Empezar

Quickstart

De cero a tu primera compra controlada en cuatro pasos. Necesitás Node instalado y un token de la API. ¿Todavía no tenés token? Creá tu cuenta →

1

Instalá el CLI

bash

$ npm install -g cardia

¿No querés instalar nada? Corré cualquier comando con npx cardia <comando>. Requiere Node 18+.

2

Configurá las variables de entorno

bash

$ export CARDIA_API_URL=https://cardia-api.emipanelli.com

$ export CARDIA_API_TOKEN=<tu-token>

El token te lo da el registro: creá tu cuenta en cardia.digital/registro. Se muestra una sola vez — guardalo bien.

3

Listá tus tarjetas

bash

$ cardia cards

4

Comprá con control

Con --max, el CLI crea el permiso y después ejecuta la compra. El resultado se muestra como ✓ APPROVED o ✗ REJECTED.

cardia

$ cardia buy --card card_01 --merchant Jumbo --amount 12000 --max 50000

✓ APPROVED · Jumbo · $12.000 ARS (permiso $50.000)

$ cardia buy --card card_01 --merchant Steam --amount 8000

✗ REJECTED · sin permiso vigente para Steam ▋

Empezar

Onboarding con Teams

cardia teams es el camino más rápido para arrancar: un wizard interactivo que crea tu empresa y emite una tarjeta para un miembro del equipo — una persona o un agente — con un límite mensual, en pesos o USDT.

bash

$ npx cardia teams

Son tres pasos:

  1. 1Tu empresa. El nombre del titular de la cuenta.
  2. 2¿A quién le das la tarjeta? Persona o agente, su nombre y la moneda (USDT o pesos).
  3. 3Límite mensual. El tope de gasto de esa tarjeta.
cardia teams

$ npx cardia teams

◆ Cardia Teams — pagos para tu equipo (gente + agentes), con control

1/3 Tu empresa

Nombre › Seenka

✓ Empresa creada: Seenka

2/3 ¿A quién le das una tarjeta?

Agente (a) o Persona (p) › a

Nombre del agente › Sheldon

Moneda — USDT (u) o Pesos (p) › u

3/3 Límite mensual

US$ › 50

✓ Tarjeta USDT creada para Sheldon (agente)

✓ Listo. Conectá el agente por MCP (ver abajo).

Cada cuenta nace con dos tarjetas (ARS y USD) y vos seguís el gasto de IA del equipo desde el panel en cardia.digital/admin.

Integraciones

Conectar un agente (MCP)

Cardia habla MCP (Model Context Protocol), el estándar para darle herramientas a un agente. Conectado el server, tu agente crea tarjetas, paga y consulta saldo en lenguaje natural — siempre dentro de los límites que definís. La decisión de gasto vive en el servidor, no en el modelo.

Opción 1 — MCP hosteado (HTTP)

El server MCP vive en https://cardia.digital/api/mcp. No instalás nada: te autenticás con tu token en el header Authorization: Bearer <tu-token> (el token viaja por request, nunca se guarda en el server). Si no tenés token, creá tu cuenta. En Claude Code, una línea:

bash

$ claude mcp add --transport http cardia https://cardia.digital/api/mcp --header "Authorization: Bearer <token>"

Para clientes que soportan MCP por HTTP (Cursor, Claude Desktop, etc.), agregá esto a la config:

mcp.json

{

"mcpServers": {

"cardia": {

"type": "http",

"url": "https://cardia.digital/api/mcp",

"headers": {

"Authorization": "Bearer <tu-token>"

}

}

}

}

Opción 2 — Server MCP local (npx cardia mcp)

Si preferís correr el server en tu máquina (stdio), el CLI lo trae incluido. En Claude Code / Claude Desktop:

bash

$ claude mcp add cardia -- npx cardia mcp

Las credenciales se toman de CARDIA_API_URL y CARDIA_API_TOKEN en el entorno (ver más abajo). Para Cursor, agregalo a ~/.cursor/mcp.json (global) o .cursor/mcp.json (del proyecto):

mcp.json

{

"mcpServers": {

"cardia": {

"command": "npx",

"args": ["cardia", "mcp"],

"env": {

"CARDIA_API_URL": "https://cardia-api.emipanelli.com",

"CARDIA_API_TOKEN": "<tu-token>"

}

}

}

}

Las 12 tools

Las dos opciones exponen el mismo set: list_cards, create_card, check_balance, set_limit, freeze_card, unfreeze_card, grant_permission, list_permissions, authorize_payment, get_transactions, create_purchase_card y reveal_card.

Tarjeta por compra (single-use)

create_purchase_card crea una tarjeta que nace atada a un comercio y un monto, devuelve los datos (PAN/CVV/vencimiento) una sola vez y muere sola tras su primer pago aprobado. El flujo: crear → datos una vez → pagar → muere. Ejemplo: le pedís al agente que compre un vuelo — crea la tarjeta por el monto exacto del pasaje, carga los datos en el checkout de la aerolínea, el pago aprueba y la tarjeta se cancela sola. Nada queda vivo. reveal_card vuelve a mostrar los datos de una tarjeta existente (si ya murió, responde que está cancelada).

Si la cuenta que respalda la tarjeta es nueva, fondeala (cash-in) antes de pagar: el saldo puede tardar ~10 segundos en verse reflejado.
OAuth: en camino. El MCP hosteado ya está en producción y se autentica con tu token. Lo próximo es OAuth, para conectar tu cuenta con un click sin copiar tokens.

Skill de Cardia

Para los agentes que soportan skills, el skill de Cardia empaqueta los comandos y el flujo de pago con control para que el agente sepa pagar sin configuración extra.

bash

$ npx skills add cardia

Próximamente.

Referencia

CLI Reference

El CLI cardia es la forma más directa de operar. Todos los comandos leen CARDIA_API_URL y CARDIA_API_TOKEN del entorno.

cardia teams

Onboarding interactivo: crea tu empresa y emite una tarjeta para un miembro (persona o agente) con límite mensual.

$ cardia teams

cardia cards

Lista tus tarjetas: id, label, ••••last4, estado y gastado / límite.

$ cardia cards

cardia grant

Crea un permiso (comercio, tope, vigencia) sin ejecutar ninguna compra.

$ cardia grant --card <id> --merchant Jumbo --max <pesos> [--ttl 1h]

cardia buy

Ejecuta una compra. Con --max crea el permiso y luego compra en un solo paso.

$ cardia buy --card <id> --merchant Jumbo --amount <pesos> [--max <pesos>] [--ttl 1h]

cardia permissions

Lista los permisos con su estado y vigencia. Filtrá por tarjeta con --card.

$ cardia permissions [--card <id>]

cardia purchase

Tarjeta por compra (single-use): nace atada a un comercio y un monto, muestra los datos una sola vez y muere tras su primer pago aprobado.

$ cardia purchase --merchant <m> --amount <pesos> [--label <l>]

cardia reveal

Vuelve a mostrar los datos (PAN/CVV/vencimiento) de una tarjeta existente. Si está cancelada, lo avisa.

$ cardia reveal --card <id>

Variables de entorno

VariableDescripción
CARDIA_API_URLURL base de la API de Cardia.
CARDIA_API_TOKENToken de autenticación. Usá el del dueño o el del agente según el rol.

Referencia

API Reference

Base: https://cardia-api.emipanelli.com. Autenticá cada request con el header x-admin-token. Los montos van en centavos.

Cuentas

GET/admin/accounts

Lista las cuentas. Cada una incluye balances: { ARS, USD } en centavos.

POST/admin/accounts/:id/cash-in

Acredita saldo. Body: { amountCents, currency, idempotencyKey }.

POST/admin/accounts/:id/cash-out

Debita saldo. Body: { amountCents, currency, idempotencyKey }.

POST/admin/accounts/:id/exchange

Convierte entre los saldos de la cuenta. Body: { fromCurrency, toCurrency, amountCents }.

Tarjetas

GET/admin/cards

Lista las tarjetas, con currency: 'ARS'|'USD' y mode: 'free'|'scoped'.

POST/admin/cards

Emite tarjetas. Sin accountId crea una cuenta nueva + 2 tarjetas (ARS y USD). Con accountId + currency emite una sola.

PATCH/admin/cards/:id/mode

Cambia el modo de la tarjeta. Body: { mode: 'free'|'scoped' }.

Permisos

GET/admin/permissions

Lista permisos. Filtrá con ?cardId=.

POST/admin/permissions

Crea un permiso. Body: { cardId, merchant, maxAmountCents, ttlSeconds }.

POST/admin/permissions/:id/cancel

Cancela un permiso vigente.

Autorizaciones

POST/admin/authorizations/simulate

Simula una compra sin ejecutarla. Body: { cardId, merchant, amountCents } → devuelve { status: 'APPROVED'|'REJECTED', reason }.

GET/admin/authorizations

Lista las transacciones (autorizaciones).

Ejemplo: simular una autorización

bash

$ curl -X POST https://cardia-api.emipanelli.com/admin/authorizations/simulate \

-H "x-admin-token: $CARDIA_API_TOKEN" \

-H "Content-Type: application/json" \

-d '{ "cardId": "card_01", "merchant": "Jumbo", "amountCents": 1200000 }'

response

{

"status": "APPROVED",

"reason": "permiso vigente · Jumbo · ≤ $50.000"

}

Conceptos

Conceptos

El autorizador

La red de pagos (Pomelo) le pega a Cardia antes de cada compra con el comercio y el monto reales— no los que dice el agente. Así se cierra la puerta al prompt-injection: el límite no depende de lo que el modelo "crea" que está comprando.

  1. 1¿Tarjeta conocida? Si la tarjeta no existe, se rechaza.
  2. 2Saldo por moneda de la tarjeta.
  3. 3Scope según el modo de la tarjeta (controlada o libre).
  4. 4Chequeo final de saldo antes de aprobar.

Scope / permisos

Un permiso habilita una compra solo si se cumplen todas estas condiciones:

  • Misma tarjeta.
  • Permiso vigente (open, no vencido).
  • Monto ≤ tope del permiso.
  • Comercio matchea (case-insensitive).
El permiso es de un solo uso: al aprobar una compra pasa a estado used.

Modos de tarjeta

scopedControlada

Deny-by-default. Solo paga donde hay un permiso vigente. Todo lo demás se rechaza.

freeLibre

Paga en cualquier comercio mientras haya saldo disponible en la moneda de la tarjeta.

Separación de poderes

El dueño (token owner) crea los permisos. El agente (token agent, acotado) solo puede comprar dentro de esos permisos — nunca crearlos. Esto evita que el agente se auto-autorice.

AcciónDueño (owner)Agente (agent)
Crear permisos✓✗
Comprar dentro de un permiso✓✓
Auto-autorizarse✗✗

Conceptos

Multi-moneda

Cada cuenta tiene dos saldos (ARS + USD) y dos tarjetas, una por moneda. Cada tarjeta gasta del saldo de su moneda:

  • La tarjeta ARS gasta del saldo ARS.
  • La tarjeta USD gasta del saldo USD.
  • Una compra USD se rechaza si no hay saldo USD — aunque sobre saldo ARS.
ARSPesos

Sincroniza con Pomelo. Fondeo por CVU.

USDDólares

Ledger interno de Cardia.

Podés mover saldo entre las dos monedas de una cuenta con la operación de exchange (POST /admin/accounts/:id/exchange).

cardia

$ cardia buy --card usd_card --merchant Vercel --amount 2000

✗ REJECTED · sin saldo USD (saldo ARS no aplica a tarjetas USD) ▋

¿Listo para darle una tarjeta a tu agente?

Sumate a la lista de espera y probá el authorizer en vivo en la demo.

Sumate →Probar la demo