How CodeSpar Works

CodeSpar is the agentic operating system for money movement in Latin America. Commerce is the wedge; money movement is the platform: commerce checkout, procurement, payroll, treasury and cross-border, over the rails the region actually uses (Pix, boleto, NF-e, WhatsApp, SPEI). Instead of integrating each regional API individually, your agent talks to CodeSpar through a single SDK, and CodeSpar handles routing, authentication, and billing.

The product registry

One runtime, named by the direction money moves. Everything below in this page (sessions, meta-tools, the router) is the machinery these products share.

The Stack

┌─────────────────────────────────────────────────┐
│  Your Agent                                     │
│  (Claude, GPT, Gemini, LangChain, CrewAI, etc.) │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────┐
│  Provider Adapter                                │
│  @codespar/claude, /openai, /vercel, /mcp, etc. │
│  Converts tools to framework format              │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────┐
│  @codespar/sdk                                   │
│  Session management, tool execution, billing     │
└──────────────────────┬──────────────────────────┘
                       │  HTTPS
┌──────────────────────▼──────────────────────────┐
│  CodeSpar API  (api.codespar.dev)                │
│  Auth, routing, usage tracking, rate limiting    │
└──────────────────────┬──────────────────────────┘
                       │  MCP Protocol
┌──────────────────────▼──────────────────────────┐
│  MCP Server Catalog                              │
│                                                  │
│  Payments   Stripe, Mercado Pago, Asaas, PagarMe │
│  Fiscal     NF-e, NFS-e, NFC-e, CT-e            │
│  Logistics  Correios, Jadlog, Melhor Envio       │
│  Messaging  WhatsApp, Twilio, SendGrid           │
│  Banking    Inter, Itaú, Bradesco, Nubank        │
│  ERP        Bling, Tiny, Omie, TOTVS             │
│  Crypto     Mercado Bitcoin, Foxbit              │
└─────────────────────────────────────────────────┘

Request Lifecycle

Every tool call follows the same path through the stack:

// The agent calls codespar_pay via the adapter
const result = await session.execute("codespar_pay", {
  method: "pix",
  amount: 15000,
  currency: "BRL",
});

POST /v1/sessions/ses_abc123/execute
Authorization: Bearer csk_live_...
Content-Type: application/json

{
  "tool": "codespar_pay",
  "params": { "method": "pix", "amount": 15000, "currency": "BRL" }
}

{
  success: true,
  data: {
    payment_id: "pay_xyz789",
    pix_qr_code: "00020126...",
    pix_copy_paste: "00020126580014br.gov.bcb...",
    amount: 15000,
    status: "pending"
  },
  duration: 430,
  server: "asaas",
  tool: "codespar_pay"
}

Sessions

A session is a scoped connection to one or more MCP servers. It's the unit of work in CodeSpar.

const session = await codespar.create("user_123", {
  servers: ["stripe", "mercadopago", "correios"],
});

// Use tools...
await session.execute("codespar_pay", { ... });
await session.execute("codespar_ship", { ... });

// Clean up
await session.close();

Key properties:

• Sessions are stateless: each tool call is independent
• Sessions are scoped: only the servers you connect are available
• Sessions are metered: each tool call is logged for observability; only settled money bills
• Sessions auto-close after 30 minutes of inactivity

See Sessions for the full lifecycle reference.

Meta-Tools

Instead of exposing every raw tool from every connected server, CodeSpar provides 15 meta-tools that abstract all routing. Here are six of them:

This reduces context window usage from ~15,000 tokens (raw tools) to ~1,800 tokens (15 meta-tools), improving agent accuracy and reducing cost.

See Tools & Meta-Tools for input schemas and response formats.

Provider Adapters

CodeSpar is framework-agnostic. Provider adapters convert Tool objects to the format each framework expects:

Every adapter exports getTools(session) to convert tools and routes execution through session.execute() so billing and audit are always tracked.

See Providers for integration guides.

Billing

One public rate card, the same for everyone, in BRL: Build, measure and think: free. Move money under mandate: 10 bps. Get paid: 1%. Never more than R$2.00 per transaction. Rails always pass through at the partner's price.

The direction of the money picks the lane:

• Build: sandbox, catalog, SDK, CLI and Meter. Free without limit, always.
• Move: money leaving your organization under a signed mandate. 10 bps, floor R$0.05, cap R$2.00 per transaction.
• Get paid: money arriving in your account. 1%, no floor, cap R$2.00 per transaction.
• Account governance: a governed account exists. R$4.90 per governed account active in the month; R$0 in a month with no outcome. Published, not yet charged.
• Operate: outcomes that do not move money (NF-e, KYC, shipping labels, messages). Included while in preview.

The first R$1,000 settled per month, per lane, per organization, is free. A full refund within 7 days reverses the fee. No minimum, no platform fee, no rev-share.

Tool calls are logged for observability but never drive billing. See Billing for the full model.

What is CodeSpar?

CodeSpar is the agentic operating system for money movement in Latin America. Commerce is the wedge; money movement is the platform. We provide a single SDK and a unified session model that lets your AI agents move money (commerce checkout, procurement, payroll, treasury and cross-border) and handle everything around it: process payments, issue invoices, ship packages, send notifications, and interact with ERPs, without integrating dozens of regional APIs yourself.

The products above are the doors into that runtime. Gate, Meter, and Collect are how you get paid; Pay, Shop, and Wallet are how your agents spend; Mandate, Receipt, Identity, Guardrails, Audit, and Router are the trust layer both sides share. Think of CodeSpar as the Stripe for AI agent money movement: where Stripe unified web payments behind one API, CodeSpar unifies the rails the region actually uses (Pix, boleto, Nota Fiscal, Correios, Mercado Envios, WhatsApp Business, and more) behind one SDK call that any AI agent can invoke.

import { CodeSpar } from "@codespar/sdk";

const codespar = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY });
const session = await codespar.create("user_123", {
  servers: ["stripe", "mercadopago", "correios"],
});

const tools = await session.tools();
// 24 tools ready for your agent to call

Who is CodeSpar for?

What can you build?

Sell side, the agent (or your endpoint) collects:

Buy side, the agent spends:

Architecture

CodeSpar sits between your AI agent and every major LatAm commerce API. Both faces converge here: a buy-side spend and a sell-side charge enter the SAME router, hit the SAME mandate and policy gates, and land in the SAME audit ledger. The side only changes which meta-tool the agent calls. The architecture has four layers:

Your Agent (Claude, GPT, Gemini, LangChain, CrewAI, or any MCP client)
    |
    v
@codespar/sdk  <-- Framework adapters: claude, openai, vercel, langchain, google-genai, mastra, crewai, autogen, llama-index, letta, camel, mcp
    |
    v
CodeSpar API (api.codespar.dev)
    |                                  Routing, auth, usage tracking, billing
    v
MCP Server Catalog
    |
    +-- Payments:    Zoop, Asaas, Pagar.me, PagSeguro, Cielo, Stone, EFI, iugu, Vindi, EBANX, Mercado Pago, Conekta, Wompi
    +-- Fiscal:      NFe.io, Focus NF-e, Facturapi, AFIP, Siigo
    +-- Logistics:   Melhor Envio, Correios, Skydropx, Andreani, Coordinadora
    +-- Messaging:   Z-API, Evolution API, Zenvia, Take Blip, RD Station
    +-- Banking:     Stark Bank, Inter, Nubank, Nequi, BCRA, Pix BCB, Open Finance, STP/SPEI
    +-- ERP:         Omie, Bling, Tiny, Conta Azul, Colppy, Alegra, Bind ERP, Belvo
    +-- E-Commerce:  VTEX, Mercado Libre, Tienda Nube
    +-- Crypto:      Mercado Bitcoin, Bitso, Circle
    +-- Protocols:   Stripe ACP, Google UCP, x402, AP2 (protocol scaffolds)
    +-- Data:        BrasilAPI

How it flows:

1. Your agent receives a user request (e.g., "Create a R$49.90 checkout link for the Pro Plan").
2. The adapter converts the agent's tool call into a CodeSpar SDK call.
3. The SDK sends the request to api.codespar.dev, which authenticates, routes, and tracks usage.
4. The API forwards the call to the appropriate MCP server (e.g., the Stripe MCP server).
5. The MCP server executes the operation against the regional API and returns structured results.
6. Results flow back through the stack to your agent, which presents them to the user.

The Complete Loop

Every agent interaction follows a consistent three-phase pattern we call the Complete Loop:

const result = await session.execute("codespar_discover", {
  query: "charge a buyer in BRL via Pix",
});

{
  "matches": [
    { "tool": "codespar_charge", "server": "asaas", "score": 0.91, "connected": true },
    { "tool": "codespar_charge", "server": "mercadopago", "score": 0.88, "connected": true }
  ]
}

const result = await session.execute("codespar_charge", {
  method: "pix",
  amount: 4990,
  currency: "BRL",
  description: "Pro Plan",
});

{
  "payment_id": "pay_abc123",
  "pix_code": "00020126580014br.gov.bcb.pix...",
  "qr_code_url": "https://api.codespar.dev/qr/pay_abc123.png",
  "amount": 4990,
  "currency": "BRL",
  "status": "pending"
}

// Chain: send the Pix code via WhatsApp
const notification = await session.execute("codespar_notify", {
  channel: "whatsapp",
  to: "+5511999887766",
  template: "pix_charge",
  variables: {
    customer_name: "Maria",
    pix_code: result.pix_code,
    amount: "R$49.90",
  },
});

The 15 Meta-Tools

Products name what you ship; meta-tools are the verbs your agent calls. They are high-level operations that abstract the underlying MCP servers: instead of calling provider-specific endpoints, your agent calls a meta-tool and CodeSpar handles the routing. They split by the side your agent plays, the same grouping you see in the sidebar.

Your agent buys: the agent spends, under a signed mandate

Your agent sells: the agent collects, as the merchant

Shared rails: both sides, no money direction

Platform at a glance

• Every major LatAm commerce API covered as an MCP server: payments, fiscal, logistics, messaging, banking, ERP, e-commerce, crypto, public data, and agentic commerce protocols
• 15 meta-tools that abstract all server routing and provide a consistent interface across 85 catalog routing lines
• Every major agent framework supported: Claude, OpenAI, Vercel AI SDK, LangChain, Google Gemini, Mastra, CrewAI, AutoGen, LlamaIndex, Letta, CAMEL-AI, plus raw MCP
• One SDK: @codespar/sdk on npm, with a single session model for all operations
• Free tools: Check (the Agent-Ready scan), the sandbox, the server Catalog, the MCP Generator, and the SDK, CLI, and Hosted MCP surfaces
• Two environments: csk_test_ keys for sandbox with mock data, csk_live_ for production

Getting Started

Next steps