---
title: Glossary
description: Definitions for key terms and concepts used throughout the CodeSpar documentation.
---

# Glossary

A reference of terms used throughout the CodeSpar documentation. Entries are organized alphabetically.

---

## Adapter

A package that converts CodeSpar [session](/docs/concepts/sessions) tools into the format expected by a specific AI framework. Adapters handle the translation between CodeSpar's MCP-based tool format and the framework's native tool/function calling interface.

Available adapters: `@codespar/claude` (Anthropic SDK), `@codespar/openai` (OpenAI SDK), `@codespar/vercel` (Vercel AI SDK), `@codespar/mcp` (Claude Desktop, Cursor, any MCP client).

## API Key

A secret token used to authenticate your application to the CodeSpar API. Each key is bound to a single project at mint time and inherits that project's `environment` field — keys minted against a `test`-environment project carry the `csk_test_` prefix; keys minted against a `live`-environment project carry the `csk_live_` prefix. A `csk_test_*` key authorizes against `test`-environment projects; tool calls route to the catalog's `base_url_test` provider sandbox where one is defined, and to the real production endpoint otherwise. Declare per-session fixtures via `cs.create({ mocks: {...} })` for deterministic responses — see [Test Mode](/docs/concepts/test-mode). A key can be restricted to specific operations (e.g. `sessions:create`, `tools:execute`) at creation, limiting what it can do if leaked. See [Authentication](/docs/concepts/authentication).

## BACR

**Build-Act-Confirm-Report.** The internal execution pattern that CodeSpar follows when processing a [tool call](#tool-call). The system **builds** the request in the provider's native format, **acts** on the provider API, **confirms** the result matches expectations, and **reports** back to the calling agent. As a developer, you do not interact with BACR directly -- it is the engine behind `session.execute()` that ensures reliability and consistency across every connected provider.

## Bearer Token

An HTTP authentication scheme where the API key is passed in the `Authorization` header as `Bearer <key>`. All requests to `api.codespar.dev` must include a bearer token. Example: `Authorization: Bearer csk_live_abc123...`. See [Authentication](/docs/concepts/authentication).

## Boleto

A Brazilian bank slip used for offline payment. The buyer receives a barcode (or printable PDF) and pays at any bank, ATM, lottery house, or supported app. Settlement is T+1 to T+3 business days. CodeSpar emits boletos through `codespar_charge` (Asaas, Mercado Pago) when `method: "boleto"` is requested.

## Budget Policy

A governance rule that limits how much an AI agent can spend through CodeSpar in a given time period. Budget policies can be set per agent, per session, or per account. When a budget limit is reached, tool calls that would result in financial transactions are blocked. Budget policies are configured in the dashboard under **Settings > Policies**.

## cert (auth_type)

An [auth type](/docs/concepts/authentication) that uses [mTLS](#mtls) — the operator uploads a client certificate, private key, and CA bundle through the Provider Connect modal, and CodeSpar establishes a mutually authenticated TLS session with the upstream provider. Used for Brazilian open-banking pilots (Banco do Brasil shipped first; Itaú / Santander / Bradesco / Caixa next batch). See [Authentication](/docs/concepts/authentication).

## CFDI

**Comprobante Fiscal Digital por Internet.** Mexico's mandatory electronic invoice format, regulated by SAT (Servicio de Administracion Tributaria). CodeSpar automates CFDI generation through the `codespar_invoice` [meta-tool](#meta-tool) with `rail: "nfci"` (Facturapi). CFDI documents must include a digital seal (sello digital) and be reported to SAT.

## Commercial Memory

A persistent data store that tracks an AI agent's past commerce interactions -- previous orders, customer preferences, payment methods used, shipping addresses, and preferred carriers. Commercial memory enables agents to provide personalized recommendations and avoid asking for information the customer has already provided. Stored per-account, encrypted at rest.

## Complete Loop

The recommended pattern for agent-commerce interactions: **Discover** available tools, **Execute** the appropriate action, **Confirm** the result. CodeSpar's `session.loop()` method encapsulates this pattern, allowing agents to describe intent in natural language and have CodeSpar handle tool selection, sequencing, and error recovery. See [Sessions](/docs/concepts/sessions).

## external_reference

The provider-side echo of an [`idempotency_key`](#idempotency_key). When CodeSpar fires an outbound call with an `idempotency_key`, the upstream provider stores it and returns it in webhook events as `external_reference` (Asaas, Mercado Pago, Stripe, Coinbase Commerce, etc.). The CodeSpar backend correlates `idempotency_key` ↔ `external_reference` to settle a [tool_call_id](#tool_call_id) — that's how `paymentStatus` and `verificationStatus` track async events without each integrator wiring webhooks themselves.

## Factura electrónica

Argentina's electronic invoice, regulated by AFIP (Administración Federal de Ingresos Públicos). CodeSpar issues Factura via the `codespar_invoice` [meta-tool](#meta-tool) with the AFIP rail.

## hmac_signed (auth_type)

An [auth type](/docs/concepts/authentication) that signs every outbound request with HMAC over a canonical string of `timestamp + method + path + body`. Used by Foxbit (Brazilian crypto exchange) and the catalog overrides for other LATAM crypto providers. The operator stores the signing secret once via `POST /v1/connections/hmac-validate` (signing-secret round-trip). See [Authentication](/docs/concepts/authentication).

## idempotency_key

A UUID-v4 string CodeSpar attaches to each outbound provider call to make the call replay-safe. It propagates upstream (so retries against Asaas / MP / Stripe don't double-charge) and is echoed back by the provider in webhook events as [`external_reference`](#external_reference). CodeSpar uses that correlation to settle the originating [tool_call_id](#tool_call_id).

## MCP

**Model Context Protocol.** An open standard created by Anthropic for connecting AI models to external tools and data sources. CodeSpar wraps every major LatAm commerce API as an MCP server, making them accessible to any MCP-compatible client (Claude Desktop, Cursor, custom agents built with any framework). MCP defines the wire format for tool definitions (`input_schema`) and tool results. [Learn more about MCP](https://modelcontextprotocol.io/).

## MCP Server

A service that exposes tools and resources following the Model Context Protocol specification. In CodeSpar, each commerce provider (Stripe, Mercado Pago, Correios, NF-e, etc.) is wrapped as an MCP server with standardized tool definitions. Servers are connected to [sessions](#session) to make their tools available to your agent. Browse the full catalog via the [Servers API](/docs/api/servers).

## Meta-tool

A canonical, provider-agnostic wrapper that routes a high-level commerce intent to the right upstream provider based on the arguments (payment method, currency, region). Meta-tools live in front of the [MCP server](#mcp-server) catalog so the LLM sees a small, stable surface instead of dozens of provider-specific tools.

The 14 current meta-tools: `codespar_pay` (outbound transfers), `codespar_charge` (inbound charges), `codespar_checkout` (sell-side merchant checkout), `codespar_shop` (buy-side shopping), `codespar_invoice` (NFS-e / NF-e / CFDI / Factura), `codespar_notify` (WhatsApp / SMS / email), `codespar_ship` (Melhor Envio rails), `codespar_crypto_pay` (Coinbase Commerce / Bitso), `codespar_kyc` (Persona / Sift / Konduto / Truora), `codespar_wallet` (the agent's governed wallet), `codespar_ledger` (double-entry ledger), `codespar_issue` (card issuing and control), `codespar_discover` (tool search), `codespar_manage_connections` (connection wizard backend). See [Tools and Meta-Tools](/docs/concepts/tools).

## mTLS

Mutual TLS — both sides of the TLS handshake authenticate with X.509 certificates, instead of just the server. CodeSpar uses mTLS to talk to Brazilian open-banking APIs that require it (Banco do Brasil, with Itaú / Santander / Bradesco / Caixa next). Configured per-connection via the [`cert`](#cert-auth_type) auth type.

## NF-e (Nota Fiscal Eletronica)

Brazil's electronic invoice for **goods**, regulated by [SEFAZ](#sefaz) at the state level. CodeSpar issues NF-e through `codespar_invoice` by passing `rail: "nfe"` (default rail is [NFS-e](#nfs-e-nota-fiscal-de-servicos-eletronica) for services). NF-e issuance requires an A1 digital certificate, state tax registration, and an ICMS classification on each item.

## NFS-e (Nota Fiscal de Servicos Eletronica)

Brazil's electronic invoice for **services** — the default rail for `codespar_invoice` (omit `rail` and you get NFS-e). Unlike NF-e (which covers goods and is state-regulated), NFS-e is regulated at the municipal level, so each city has its own rules and endpoints. CodeSpar normalizes that complexity behind a single meta-tool call.

## Open Finance (BR)

Brazil's open-banking framework, mandated by the Banco Central do Brasil. Banks expose payment-initiation, account, and credit APIs over [mTLS](#mtls) so authorized third parties can transact on a customer's behalf. CodeSpar accesses Open Finance APIs through the [`cert`](#cert-auth_type) auth type — Banco do Brasil pilot shipped, Itaú / Santander / Bradesco / Caixa next batch.

## Pix

Brazil's instant payment system operated by the Central Bank (Banco Central do Brasil). Pix transfers settle in seconds, operate 24/7/365, and are free for individuals. Several CodeSpar payment servers support Pix, including Stripe, Mercado Pago, Asaas, and PagSeguro. When processing a Pix payment through `codespar_pay`, CodeSpar returns a Pix copy-paste code and a QR code URL.

## Preset

A named shortcut for a common combination of [MCP servers](#mcp-server). Instead of listing servers individually when creating a [session](#session), you can pass a preset name (e.g., `"payments"`, `"brazilian"`, `"ecommerce"`). Presets can be combined with explicit `servers` arrays. See [Sessions](/docs/concepts/sessions).

## Provider

A third-party commerce service -- payment gateway, shipping carrier, fiscal authority, messaging platform, banking API, ERP, or crypto exchange -- that CodeSpar integrates with. Each provider is wrapped as an [MCP server](#mcp-server). Examples: Stripe, Mercado Pago, Correios, Twilio, SEFAZ.

## Routing rail

The unit of routing inside a [meta-tool](#meta-tool) — the tuple `(meta_tool, rail, provider)`. For example, `codespar_ship` exposes three rails: `domestic-label`, `domestic-quote`, `domestic-track`, all routed to Melhor Envio. `codespar_invoice` has rails for NFS-e (default), NF-e (`rail: "nfe"`), CFDI MX, and Factura AR. There are 60+ routing rails today across 14 meta-tools and six countries (BR, MX, AR, CO, CL, PE).

## Sandbox

Two distinct surfaces share the name:

- The **in-dashboard sandbox** at [`/dashboard/sandbox`](https://codespar.dev/dashboard/sandbox) — a hosted chat interface for picking tools and watching them dispatch against your connected providers, no code required.
- An **upstream provider sandbox** — the test endpoint a provider publishes (e.g. Asaas, Stripe, Mercado Pago each ship one). The CodeSpar catalog records these as `base_url_test`, and tool calls under a `csk_test_*` [API key](#api-key) route there where the catalog defines one, falling back to the real production endpoint otherwise.

Neither surface is the same as **SDK test mode** — the per-session `mocks` field on `cs.create` that substitutes deterministic fixtures for upstream calls. See [Test Mode](/docs/concepts/test-mode) for that contract.

## SEFAZ

**Secretaria da Fazenda.** The state-level tax authority in Brazil responsible for authorizing fiscal documents like [NF-e](#nf-e-nota-fiscal-eletronica). Each of Brazil's 27 states operates its own SEFAZ instance. CodeSpar's fiscal rail targets SEFAZ authorization for issuing, cancelling, and querying NF-e documents; the flow is validated against the provider sandbox today, with production SEFAZ authorization on the roadmap.

## Service Auth

How CodeSpar authenticates to third-party commerce providers (Stripe, Mercado Pago, …) on your behalf. You store each provider's credentials once in the dashboard under **Auth Configs**; CodeSpar injects them at request time so your agent code never sees a provider secret. See [Authentication](/docs/concepts/authentication).

## Session

A scoped, authenticated connection to one or more [MCP servers](#mcp-server). Sessions manage which tools your agent can access, handle server authentication via stored credentials, and track usage for [billing](#tool-call). Sessions expire after 30 minutes of inactivity. Created via the SDK (`codespar.create(userId, config)`) or the [Sessions API](/docs/api/sessions). See [Sessions](/docs/concepts/sessions).

## SessionBase vs Session

Two layers of the SDK type model. `SessionBase` is the OSS interface — the methods every Session implementation must satisfy (`tools`, `findTools`, `execute`, `send`, `sendStream`, `connections`, `authorize`, `close`, `loop`). `Session` is what `cs.create()` returns: it implements `SessionBase` and adds the typed wrappers (`charge`, `ship`, `discover`, `connectionWizard`, `paymentStatus`, `paymentStatusStream`, `verificationStatus`, `verificationStatusStream`). Code that only depends on `SessionBase` works against any conforming implementation; code that uses the typed wrappers needs `Session`.

## SPEI

**Sistema de Pagos Electronicos Interbancarios.** Mexico's electronic interbank payment system, analogous to Brazil's [Pix](#pix). SPEI transfers settle within seconds during banking hours and are widely used for e-commerce payments. Supported through CodeSpar's Mexican payment servers (Conekta, Stripe).

## SSE (Server-Sent Events)

A one-way HTTP streaming protocol — the server pushes named events to the client over a single long-lived connection. CodeSpar exposes SSE on `GET /v1/tool-calls/:id/payment-status/stream` and `…/verification-status/stream` for low-latency settlement updates. The SDK wraps these as `paymentStatusStream` and `verificationStatusStream`. Heartbeat every 15 seconds; auto-closes 5 seconds after a terminal state. Pick SSE over [polling](/docs/api/sdk) for long-running pending → settled flows.

## Tool

A function exposed by an [MCP server](#mcp-server) that an AI agent can call. Each tool has a `name` (e.g., `codespar_pay`), a `description` (natural language for the LLM), and an `input_schema` (JSON Schema defining the parameters). Tools are accessed through [sessions](#session).

## Tool Call

A single invocation of a [tool](#tool) through a session. Tool calls are the billing unit in CodeSpar -- each `session.execute()`, `session.send()`, or `session.sendStream()` counts as one tool call. See [Billing and Quotas](/docs/concepts/billing).

## tool_call_id

The server-side identifier returned on every tool-call result (`session.execute(...)`, `session.charge(...)`, `session.pay(...)`, etc.). Pass it to `GET /v1/tool-calls/:id/payment-status` (or the [SDK](/docs/api/sdk) `paymentStatus` / `paymentStatusStream`) to track settlement of an inbound charge or outbound transfer, and to `…/verification-status` (or `verificationStatus` / `verificationStatusStream`) for KYC inquiries. Internally the backend correlates this against the [`idempotency_key`](#idempotency_key) ↔ provider [`external_reference`](#external_reference) round-trip.

## Trigger

A webhook-based automation that fires when a specific event occurs in a connected provider. For example, a trigger can notify your agent when a Pix payment is confirmed or when a shipping status changes. Triggers are configured via the [Triggers API](/docs/api/sessions) and deliver events to a webhook URL you specify.

## Trust Graph

A data structure that maps trust relationships between AI agents and commerce providers. The trust graph tracks which agents have been authorized to perform which operations (e.g., "Agent X can process payments up to R$500 via Stripe but cannot issue refunds"). Trust graphs are managed per-account and enforced at the session level.

## Webhook

An HTTP callback sent by CodeSpar to your application when an asynchronous event completes. In CodeSpar the underlying object is called a [trigger](#trigger) — register one via `POST /v1/triggers` and CodeSpar delivers signed HTTP POSTs on matching events (`payment.confirmed`, `invoice.authorized`, `shipment.in_transit`, `message.delivered`, etc.).

CodeSpar → integrator outbound webhooks are signed with `X-CodeSpar-Signature` using HMAC-SHA256 (hex-encoded) of the raw request body — verify against the signing secret returned once on trigger creation.

INBOUND webhook adapters (provider → CodeSpar) verify per-provider with one of: HMAC-SHA256, ECDSA P-256, HTTP Basic (e.g. Sift, Konduto — operator stores `Basic <base64>` as bearer), or shared-secret comparison. The CodeSpar backend handles inbound verification; integrators don't see provider-side signatures. See [Triggers](/docs/concepts/triggers).