Introduction
The agentic operating system for money movement in Latin America. Commerce is the wedge; money movement is the platform.
See both sides run
Same infrastructure, same governance. Watch the direction of money flip while the mandate gate, the router, and the receipt stay identical.
↘ You get paid
↗ You send agents out to spend
✦ Either way, the same artifact
Every settled move on either side seals a signed receipt binding permission, settlement, and proof:
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 callCodeSpar is not another agent framework. It is the commerce layer that plugs into any agent framework: Claude, OpenAI, Vercel AI SDK, or any MCP-compatible client. You keep your agent architecture; CodeSpar gives it the ability to transact.
Who is CodeSpar for?
| Audience | What CodeSpar solves | Typical side |
|---|---|---|
| AI engineers | Ship money-movement features in hours instead of weeks. No need to learn Pix settlement, NF-e XML schemas, or carrier APIs. | Both |
| API and MCP builders | Get paid per call by agents: a Gate paywall in front of what you already run, no signup for the caller. | Sell |
| Consumer / agent apps | Give an agent a governed wallet and let it shop and pay for the user, inside caps the user signed. | Buy |
| SaaS companies | Add AI-powered commerce workflows to your product. Let your users' agents sell, invoice, and ship. | Sell |
| Fintechs and ERPs | Expose your services to AI agents via MCP without building your own tool layer. | Both |
| Enterprise teams | Centralized governance, usage tracking, and billing across all agent money movement: procurement, payroll, treasury. | Buy |
What can you build?
Sell side, the agent (or your endpoint) collects:
| Use case | How it works | Built on |
|---|---|---|
| Paid API for agents | A Gate paywall answers 402, settles USDC per call, and proxies to your backend | Gate |
| Usage-priced inference | The buyer signs a ceiling; the actual cost is metered from your response and the difference refunds on-chain | Meter (beta) |
| AI sales agent on WhatsApp | Agent charges via Pix and sends the receipt in the chat | codespar_charge, codespar_notify |
| Automated invoicing | Agent issues the fiscal document after every sale | codespar_invoice |
| Payment reconciliation | Agent monitors incoming Pix, matches to orders, triggers fulfillment | codespar_charge, codespar_ledger |
| End-to-end commerce | Charge, invoice, ship, notify: the full loop in one conversation | codespar_charge, codespar_invoice, codespar_ship, codespar_notify |
Buy side, the agent spends:
| Use case | How it works | Built on |
|---|---|---|
| Shopping agent | Searches a real store, drives the checkout, pays the store's Pix from its governed wallet | Shop, Wallet, Pay |
| Contas a pagar / procurement | Agent pays suppliers on schedule, every payment capped by the mandate | Pay, codespar_ledger |
| Machine spend on x402 | An x402-priced API answers with a quote; the agent settles it in USDC inside the per-tx cap | Pay, Wallet |
| Treasury under mandate | Move balance between BRL and USDC slots of one wallet, no FX guessing | Wallet |
| Bulk refunds | Refund a batch of payments in parallel, partial failures handled | Pay |
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: BrasilAPIHow it flows:
- Your agent receives a user request (e.g., "Create a R$49.90 checkout link for the Pro Plan").
- The adapter converts the agent's tool call into a CodeSpar SDK call.
- The SDK sends the request to
api.codespar.dev, which authenticates, routes, and tracks usage. - The API forwards the call to the appropriate MCP server (e.g., the Stripe MCP server).
- The MCP server executes the operation against the regional API and returns structured results.
- Results flow back through the stack to your agent, which presents them to the user.
You never interact with MCP servers directly. The 15 meta-tools abstract all server routing. Call codespar_charge and CodeSpar routes it to the right payment provider based on your session configuration.
The Complete Loop
Every agent interaction follows a consistent three-phase pattern we call the Complete Loop:
Discover
The agent calls codespar_discover to search the catalog for the right tool. The query is a natural-language string; results are ranked by semantic similarity and biased toward providers already connected to the session.
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 }
]
}Execute
The agent calls the appropriate meta-tool. CodeSpar routes the request to the correct MCP server based on the session's server configuration.
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"
}Confirm
CodeSpar returns structured results. The agent can present them to the user, chain into the next step (e.g., send the Pix code via WhatsApp), or store them for later reference.
// 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
| Meta-tool | Purpose | Example operation |
|---|---|---|
codespar_shop | Search and buy from real stores; async checkout session to the store's payable Pix | "Find dog food under R$100 and buy the best one" |
codespar_wallet | The agent's governed funds: balance, statement, top-up; per-currency slots | "Show the wallet balance in BRL and USDC" |
codespar_pay | Outbound spend: money leaves the wallet the agent governs | "Pay R$1,500 to the supplier via Pix" |
codespar_crypto_pay | On-chain spend and cross-border ramps (testnet today) | "Pay 25 USDC to this 0x address" |
codespar_issue | Spend cards bound to the same mandate governance | "Issue a virtual card for the travel agent" |
Your agent sells: the agent collects, as the merchant
| Meta-tool | Purpose | Example operation |
|---|---|---|
codespar_checkout | Assemble a cart and dispatch it as a charge with a hosted payment page | "Create a R$99 checkout for the Pro Plan" |
codespar_charge | Inbound charges: the buyer pays you | "Generate a Pix QR code for R$250" |
codespar_invoice | Fiscal documents (NFS-e default; NF-e, CFDI, Factura AR) | "Issue the invoice for order #1234" |
codespar_ship | Quote, label, and track shipments | "Ship 2kg from SP to RJ" |
codespar_notify | Messages via WhatsApp, SMS, email | "Send the order confirmation via WhatsApp" |
codespar_kyc | Verify counterparties before money moves | "Verify this customer before the payout" |
Shared rails: both sides, no money direction
| Meta-tool | Purpose | Example operation |
|---|---|---|
codespar_ledger | Double-entry books + the signed agentic receipts | "List this month's entries for the escrow account" |
codespar_discover | Semantic search across the catalog | "Find tools that charge in BRL via Pix" |
codespar_manage_connections | Providers, credentials, and shopper identity | "Connect WhatsApp for notifications" |
codespar_get_started | The ordered happy path for this workspace: what is connected, what to connect next, what to call first | "How do I start? What can you do?" |
See Tools and Meta-Tools for the full reference, including input schemas and response formats for each meta-tool.
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 60+ catalog rails
- 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/sdkon 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 MCP surfaces
- Two environments:
csk_test_keys for sandbox with mock data,csk_live_for production