Glossary

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

---

Adapter

A package that converts CodeSpar session 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. Keys use the prefix csk_live_ for production and csk_test_ for sandbox environments. Each key can be scoped to specific permissions (e.g., sessions:create, tools:execute). See Authentication.

BACR

Build-Act-Confirm-Report. The internal execution pattern that CodeSpar follows when processing a 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.

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 organization. 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 that uses 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.

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 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-organization, 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.

external_reference

The provider-side echo of an 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 — 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 with the AFIP rail.

hmac_signed (auth_type)

An auth type 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.

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. CodeSpar uses that correlation to settle the originating 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.

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 to make their tools available to your agent. Browse the full catalog via the Servers API.

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 catalog so the LLM sees a small, stable surface instead of dozens of provider-specific tools.

The nine current meta-tools: codespar_pay (outbound transfers), codespar_charge (inbound charges), 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_discover (tool search), codespar_manage_connections (connection wizard backend). See Tools and Meta-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 auth type.

NF-e (Nota Fiscal Eletronica)

Brazil's electronic invoice for goods, regulated by SEFAZ at the state level. CodeSpar issues NF-e through codespar_invoice by passing rail: "nfe" (default rail is NFS-e 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 so authorized third parties can transact on a customer's behalf. CodeSpar accesses Open Finance APIs through the cert 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. Instead of listing servers individually when creating a session, you can pass a preset name (e.g., "payments", "brazilian", "ecommerce"). Presets can be combined with explicit servers arrays. See 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. Examples: Stripe, Mercado Pago, Correios, Twilio, SEFAZ.

Routing rail

The unit of routing inside a 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 53 routing rails today across nine meta-tools and six countries (BR, MX, AR, CO, CL, PE).

Sandbox

A testing environment accessed with csk_test_ API keys. Sandbox sessions connect to mock servers that return realistic simulated data without processing real transactions, issuing real invoices, or sending real messages. The mock data follows the same schema as production responses. Also refers to the interactive sandbox in the dashboard for experimenting with tool calls.

SEFAZ

Secretaria da Fazenda. The state-level tax authority in Brazil responsible for authorizing fiscal documents like NF-e. Each of Brazil's 27 states operates its own SEFAZ instance. CodeSpar's fiscal servers communicate with SEFAZ in real time to authorize, cancel, and query NF-e documents.

Service Auth

A secondary authentication mechanism using the x-codespar-service-key header, designed for trusted server-to-server communication. Service keys (cssk_internal_) have elevated permissions, bypass rate limits, and can access sessions across an entire organization. See Authentication.

Session

A scoped, authenticated connection to one or more MCP servers. Sessions manage which tools your agent can access, handle server authentication via stored credentials, and track usage for billing. Sessions expire after 30 minutes of inactivity. Created via the SDK (codespar.create(userId, config)) or the Sessions API. See 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. 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 for long-running pending → settled flows.

Tool

A function exposed by an 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.

Tool Call

A single invocation of a 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.

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 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 ↔ provider 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 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-organization 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 — 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.