@ar-agents/banking

Argentine banking primitives for Vercel AI SDK 6+ agents: CBU/CVU validation, bank/PSP lookup, and BCRA Central de Deudores.

Reading this as an agent? Skip to AGENTS.md for tool selection rules, result schemas to memorize, error patterns, and AR banking context.

At a glance

| What | Value | | --- | --- | | Tools shipped | 5: validate_cbu, lookup_bank_by_code, list_banks, list_psps, lookup_credit_situation | | Pure-algorithm | validate_cbu + lookup_bank_by_code + bank/PSP lists work with zero setup (no API key) | | External adapter | BcraPublicApiAdapter (default: public BCRA API, no auth) for credit-situation lookups | | Banks + PSPs covered | All 60+ AR banks (Galicia, Nación, BBVA, Santander…) + 20+ PSPs (Mercado Pago, Ualá, Naranja X, Modo, Cuenta DNI…) | | Test coverage | 54 unit tests, 90% statements, 100% functions | | Bundle | 5.3 KB ESM brotli'd | | Runtime | Edge Runtime + Node 18+ (pure compute, no node:crypto) |

Built for agents that need to:

• Validate CBUs/CVUs before initiating transfers (catch typos before they cost you a chargeback)
• Identify the bank or PSP behind a CBU (Galicia, Nación, Mercado Pago, Ualá, Naranja X…)
• Check BCRA credit situation for B2B counterparty risk (factoring, supplier onboarding)

Ships with pure-algorithm tools that always work (no API key, no setup) and a pluggable BCRA adapter for credit lookups.

Install

pnpm add @ar-agents/banking
# peer deps: ai >=6, zod >=3

Quick start

import { Experimental_Agent as Agent, stepCountIs } from "ai";
import { bankingTools, BcraPublicApiAdapter } from "@ar-agents/banking";

const agent = new Agent({
  model: "anthropic/claude-sonnet-4-6",
  tools: bankingTools({
    bcra: new BcraPublicApiAdapter(), // optional: for credit lookups
  }),
  stopWhen: stepCountIs(6),
});

const { text } = await agent.generate({
  prompt: "Validá este CBU: 0070123145678901234564",
});
// → "Es un CBU válido. Banco: Banco Galicia, sucursal 0123, cuenta 4567890123456."

Without a BCRA adapter, the credit-lookup tool stays callable but returns { available: false, error: "<setup instructions>" } instead of crashing.

Tools

| Tool | Pure? | What it does | | -------------------------- | ----- | -------------------------------------------------------- | | validate_cbu | ✓ | Validate CBU/CVU + identify bank/PSP | | lookup_bank_by_code | ✓ | Resolve a 3-digit bank code or 7-digit CVU prefix → name | | list_banks | ✓ | Enumerate all known banks (for dropdowns) | | list_psps | ✓ | Enumerate all known PSPs/fintechs (for dropdowns) | | lookup_credit_situation |: | BCRA Central de Deudores lookup (requires adapter) |

See AGENTS.md for detailed selection guidance and result schemas.

CBU/CVU algorithm

CBU = Clave Bancaria Uniforme (traditional bank accounts). CVU = Clave Virtual Uniforme (PSPs / fintechs / digital wallets).

Both are 22 digits with the BCRA dual mod-10 check-digit algorithm:

• Block 1 (8 digits): BBB-SSSS-V₁: entity (3) + branch (4) + check (1)
• Block 2 (14 digits): <account-13>-V₂: account (13) + check (1)

The algorithm is implemented in src/cbu.ts and exposed via parseCbu(), isValidCbu(), and computeBlockCheckDigit(). Pure functions, sub-millisecond, no I/O.

BCRA Central de Deudores

For B2B agents that need credit-risk signal on a counterparty CUIT:

import { bankingTools, BcraPublicApiAdapter } from "@ar-agents/banking";

const tools = bankingTools({
  bcra: new BcraPublicApiAdapter({
    requestTimeoutMs: 15_000,
    maxRetries: 2,
    onCall: (e) => console.log(e), // observability hook
  }),
});

The default adapter hits BCRA's public REST endpoint (api.bcra.gob.ar/centraldedeudores/v1.0/Deudas/{cuit}): no auth required, respect their rate limits. You can swap in your own adapter for caching, NOSIS, Equifax, or a private mirror.

Returns a normalized BcraDeudaResult with the worst situation code (1–6), total outstanding debt across all entities, and per-entity breakdown.

See BcraSituation in src/types.ts for the situation-code reference (1=normal, 5=irrecuperable, etc.).

License

MIT © Nazareno Clemente

Stability

This package is pre-1.0. Per npm convention, 0.x minor versions may include breaking changes. We document every breaking change in CHANGELOG.md under the corresponding minor bump and flag it explicitly. To avoid surprises:

# Pin to exact version (recommended for production):
pnpm add @ar-agents/<package>@<exact-version>

We commit to no breaking changes within a patch version, and we publish 1.0.0 once the public API has stabilized across at least two consecutive minor releases.