---
title: Introduction
description: The agentic operating system for money movement in Latin America. Commerce is the wedge; money movement is the platform.
hero: true
---

import { Cards, Card } from "fumadocs-ui/components/card";
import { Callout } from "fumadocs-ui/components/callout";
import { Step, Steps } from "fumadocs-ui/components/steps";

<DocsHero
  eyebrow="Documentation"
  pkg="@codespar/sdk"
  title="The agentic OS for money movement in Latin America."
  description="Commerce checkout, procurement, payroll, treasury and cross-border, over the rails the region actually uses (Pix, boleto, NF-e, WhatsApp, SPEI), behind one SDK and fourteen meta-tools, governed by signed mandates."
  links={[
    {
      label: "Start here",
      title: "Quickstart",
      description: "Install the SDK, create a session, and ship a commerce agent in under 5 minutes.",
      href: "/docs/quickstart",
    },
    {
      label: "Concepts",
      title: "How CodeSpar Works",
      description: "Architecture, request lifecycle, and the Complete Loop explained.",
      href: "/docs/how-it-works",
    },
    {
      label: "Reference",
      title: "SDK Reference",
      description: "Every method, type, and session primitive in the @codespar/sdk package.",
      href: "/docs/api/sdk",
    },
  ]}
/>

<DomainGrid
  title="Which side is your agent on?"
  subtitle="ONE infrastructure, two faces. The router, catalog, mandates, and audit ledger underneath are the same; what changes is the direction money moves. Start from the side your agent plays."
  domains={[
    {
      title: "Your agent BUYS",
      description: "The agent is the shopper: it spends under a signed mandate. Shop real stores, hold a multi-slot wallet (BRL + USDC), pay on Pix or on-chain, issue spend cards. Tools: shop, wallet, pay, crypto_pay, issue.",
      href: "/docs/quickstart-buyer",
      icon: "↗",
      accent: "#3B82F6",
    },
    {
      title: "Your agent SELLS",
      description: "The agent is the merchant: it collects. Create checkouts and charges, issue fiscal documents, ship, notify, KYC counterparties. Tools: checkout, charge, invoice, ship, notify, kyc.",
      href: "/docs/quickstart",
      icon: "↘",
      accent: "#10B981",
    },
    {
      title: "Shared rails",
      description: "Both sides ride the same books and discovery: ledger (double-entry + signed receipts), discover (tool search), manage_connections (credentials and identity).",
      href: "/docs/concepts/tools",
      icon: "≡",
      accent: "#8B5CF6",
    },
  ]}
/>

## 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.

### ↗ Your agent BUYS

<MoneyFlowDiagram side="buy" />

<ChatPreview
  agentName="buyer agent"
  sessionId="sb_buy_idx"
  messages={[
    { role: "user", content: "Buy the cheapest ração golden 15kg at Cobasi and pay with my wallet." },
    { role: "agent", content: "Encontrei por R$ 179,90. Checkout da loja pronto, Pix gerado. Pagando com a carteira, dentro do mandato (cap R$ 500/mês)..." },
    { role: "agent", content: "Pago. Recibo assinado `rcp_8f2a` gravado no ledger. Restante do mandato: R$ 320,10." },
  ]}
  toolCalls={[
    { name: "codespar_shop", server: "checkout", status: "done", duration: "84s" },
    { name: "codespar_wallet", server: "balance", status: "done", duration: "180ms" },
    { name: "codespar_pay", server: "pix", status: "done", duration: "1.4s" },
  ]}
  footer="mandate-gated spend · signed receipt · audit chain"
  sandboxLink="/dashboard/sandbox"
/>

### ↘ Your agent SELLS

<MoneyFlowDiagram side="sell" />

<ChatPreview
  agentName="seller agent"
  sessionId="sb_sell_idx"
  messages={[
    { role: "user", content: "Charge R$249 for the Pro Plan and send the Pix code to +55 11 99988-7766 on WhatsApp." },
    { role: "agent", content: "Cobrança criada. Enviando o copia-e-cola no WhatsApp do cliente..." },
    { role: "agent", content: "Enviado. Quando o Pix liquidar, emito a NFS-e e te aviso." },
  ]}
  toolCalls={[
    { name: "codespar_charge", server: "pix", status: "done", duration: "620ms" },
    { name: "codespar_notify", server: "whatsapp", status: "done", duration: "340ms" },
    { name: "codespar_invoice", server: "nfse", status: "pending", duration: "on settle" },
  ]}
  footer="inbound charge · fiscal document on settlement · same audit chain"
  sandboxLink="/dashboard/sandbox"
/>

### ✦ Either way, the same artifact

Every settled move on either side seals a signed receipt binding permission, settlement, and proof:

<ReceiptCard />

<DomainGrid
  title="Browse by commerce domain"
  subtitle="A second lens on the same rails: the domains below serve both sides — a charge and a payment ride the same Pix providers. Pick a domain to jump to the catalog, the meta-tool, and the cookbook."
  domains={[
    {
      title: "Payments",
      description: "Pix, boleto, card, SPEI — charge, refund, payout across every major LatAm processor.",
      href: "/docs/concepts/tools#codespar_pay",
      icon: "$",
      accent: "#3B82F6",
    },
    {
      title: "Fiscal",
      description: "NF-e, NFS-e, CFDI, AFIP. Automated invoicing in BR, MX, AR, CO.",
      href: "/docs/concepts/tools#codespar_invoice",
      icon: "§",
      accent: "#8B5CF6",
    },
    {
      title: "Logistics",
      description: "Correios, Melhor Envio, Skydropx, Andreani — quote, label, track.",
      href: "/docs/concepts/tools#codespar_ship",
      icon: "→",
      accent: "#10B981",
    },
    {
      title: "Messaging",
      description: "WhatsApp, SMS, email via Z-API, Evolution, Zenvia, Take Blip.",
      href: "/docs/concepts/tools#codespar_notify",
      icon: "✉",
      accent: "#F59E0B",
    },
    {
      title: "Banking",
      description: "Stark Bank, Inter, Nubank, Nequi, Open Finance — statements, transfers, Pix BCB.",
      href: "/docs/servers#banking-7-servers",
      icon: "⛃",
      accent: "#06B6D4",
    },
    {
      title: "ERP & Accounting",
      description: "Omie, Bling, Tiny, Conta Azul, Siigo — sync products, orders, financials.",
      href: "/docs/servers#erp-accounting-7-servers",
      icon: "⊞",
      accent: "#F472B6",
    },
  ]}
/>

## 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.

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.

```typescript
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
```

<Callout type="info">
CodeSpar 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.
</Callout>
## 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 |
| **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 |
| **Agencies** | Build commerce automations for clients across Latin America with a single integration. | Both |
| **Enterprise teams** | Centralized governance, usage tracking, and billing across all agent money movement — procurement, payroll, treasury. | Buy |

## What can you build?

**Buy-side** — the agent spends:

| Use case | How it works | Meta-tools used |
|----------|-------------|-----------------|
| Shopping agent | Searches a real store, drives the checkout, pays the store's Pix from its governed wallet | `codespar_shop`, `codespar_wallet`, `codespar_pay` |
| Contas a pagar / procurement | Agent pays suppliers on schedule, every payment capped by the mandate | `codespar_pay`, `codespar_ledger` |
| Treasury under mandate | Move balance between BRL and USDC slots of one wallet, no FX guessing | `codespar_wallet` |
| Bulk refunds | Refund a batch of payments in parallel, partial failures handled | `codespar_pay` |
| Agent with a card | Issue a governed virtual card; every authorization checked server-side | `codespar_issue` |

**Sell-side** — the agent collects:

| Use case | How it works | Meta-tools used |
|----------|-------------|-----------------|
| 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` |
| Shipping automation | Agent quotes carriers, creates labels, tracks packages | `codespar_ship` |
| Payment reconciliation | Agent monitors incoming Pix, matches to orders, triggers fulfillment | `codespar_charge`, `codespar_ledger` |
| Marketplace payouts | Agent settles vendors after a sale clears | `codespar_pay` |
| End-to-end commerce | Charge, invoice, ship, notify — the full loop in one conversation | `codespar_charge`, `codespar_invoice`, `codespar_ship`, `codespar_notify` |

## 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:      Nuvem Fiscal, 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.

<Callout type="info">
You never interact with MCP servers directly. The 14 meta-tools abstract all server routing. Call `codespar_charge` and CodeSpar routes it to the right payment provider based on your session configuration.
</Callout>
## The Complete Loop

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

<Steps>
<Step>
### 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.

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

```json
{
  "matches": [
    { "tool": "codespar_charge", "server": "asaas", "score": 0.91, "connected": true },
    { "tool": "codespar_charge", "server": "mercadopago", "score": 0.88, "connected": true }
  ]
}
```
</Step>
<Step>
### Execute

The agent calls the appropriate meta-tool. CodeSpar routes the request to the correct MCP server based on the session's server configuration.

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

```json
{
  "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"
}
```
</Step>
<Step>
### 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.

```typescript
// 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",
  },
});
```
</Step>
</Steps>

## The 14 Meta-Tools

Meta-tools 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`](/docs/concepts/meta-tools/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`](/docs/concepts/meta-tools/wallet) | The agent's governed funds: balance, statement, top-up; per-currency slots | "Show the wallet balance in BRL and USDC" |
| [`codespar_pay`](/docs/concepts/meta-tools/pay) | Outbound spend — money leaves the wallet the agent governs | "Pay R$1,500 to the supplier via Pix" |
| [`codespar_crypto_pay`](/docs/concepts/meta-tools/crypto-pay) | On-chain spend and cross-border ramps (testnet today) | "Pay 25 USDC to this 0x address" |
| [`codespar_issue`](/docs/concepts/meta-tools/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`](/docs/concepts/meta-tools/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`](/docs/concepts/meta-tools/charge) | Inbound charges — the buyer pays you | "Generate a Pix QR code for R$250" |
| [`codespar_invoice`](/docs/concepts/meta-tools/invoice) | Fiscal documents (NFS-e default; NF-e, CFDI, Factura AR) | "Issue the invoice for order #1234" |
| [`codespar_ship`](/docs/concepts/meta-tools/ship) | Quote, label, and track shipments | "Ship 2kg from SP to RJ" |
| [`codespar_notify`](/docs/concepts/meta-tools/notify) | Messages via WhatsApp, SMS, email | "Send the order confirmation via WhatsApp" |
| [`codespar_kyc`](/docs/concepts/meta-tools/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`](/docs/concepts/meta-tools/ledger) | Double-entry books + the signed agentic receipts | "List this month's entries for the escrow account" |
| [`codespar_discover`](/docs/concepts/meta-tools/discover) | Semantic search across the catalog | "Find tools that charge in BRL via Pix" |
| [`codespar_manage_connections`](/docs/concepts/meta-tools/manage-connections) | Providers, credentials, and shopper identity | "Connect WhatsApp for notifications" |

<Callout type="info">
See [Tools and Meta-Tools](/docs/concepts/tools) for the full reference, including input schemas and response formats for each meta-tool.
</Callout>
## 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
- **14 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/sdk` on npm, with a single session model for all operations
- **Published under `@codespar`** — every server and adapter available as its own npm package
- **Two environments** — `csk_test_` keys for sandbox with mock data, `csk_live_` for production

## Getting Started

<NextStepsGrid items={[
  { label: "BUY-SIDE", title: "Quickstart (Buyer agent)", description: "MCP-first, no code: your coding agent shops a real store and pays under a mandate.", href: "/docs/quickstart-buyer" },
  { label: "SELL-SIDE", title: "Quickstart", description: "Install the SDK, create a session, charge and invoice in one loop.", href: "/docs/quickstart" },
  { label: "QUICKSTART", title: "Quickstart (Python)", description: "Same flow in sync / async Python.", href: "/docs/quickstart-python" },
  { label: "CONCEPT", title: "Sessions", description: "Session lifecycle, server selection, and scoping model.", href: "/docs/concepts/sessions" },
  { label: "CONCEPT", title: "Tools & Meta-Tools", description: "How the 14 meta-tools work and what each one does.", href: "/docs/concepts/tools" },
  { label: "PROVIDER", title: "Claude Adapter", description: "Build a commerce agent with the Anthropic Claude SDK.", href: "/docs/providers/claude" },
  { label: "PROVIDER", title: "OpenAI Adapter", description: "Integrate with GPT-4o and the OpenAI SDK.", href: "/docs/providers/openai" },
  { label: "PROVIDER", title: "Vercel AI SDK", description: "Streaming-first commerce agents for Next.js.", href: "/docs/providers/vercel" },
  { label: "PROVIDER", title: "MCP", description: "Use CodeSpar tools in Claude Desktop, Cursor, and Windsurf.", href: "/docs/providers/mcp" },
  { label: "CONCEPT", title: "Authentication", description: "API keys, environments, and security model.", href: "/docs/concepts/authentication" },
]} />