---
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 fifteen meta-tools, governed by signed mandates."
  links={[
    {
      label: "Sell side",
      title: "Quickstart: get paid",
      description: "Put an x402 paywall in front of your API and take the first paid call in five minutes.",
      href: "/docs/quickstart-seller",
    },
    {
      label: "Buy side",
      title: "Quickstart: buyer agent",
      description: "Give your coding agent a governed wallet and let it shop and pay under a signed mandate.",
      href: "/docs/quickstart-buyer",
    },
    {
      label: "Concepts",
      title: "How CodeSpar Works",
      description: "Architecture, request lifecycle, and the Complete Loop explained.",
      href: "/docs/how-it-works",
    },
  ]}
/>

<DomainGrid
  title="You get paid."
  subtitle="The sell side: price what your endpoints and agents do, and settle to a wallet you control. Gate is live on Base mainnet with real USDC. Meter is in beta during final mainnet validation. Collect links are in early access."
  domains={[
    {
      title: "Gate",
      description: "Paywall any API or MCP server. An unpaid call gets an HTTP 402; a paid one settles USDC on Base and is proxied to your upstream with a sealed receipt. Live on Base mainnet.",
      href: "/docs/concepts/gate",
      icon: "⧉",
      accent: "#10B981",
    },
    {
      title: "Meter",
      description: "Post-paid pricing on a Gate paywall. The buyer signs a ceiling, your upstream reports the actual work, and the difference is refunded on-chain. Beta.",
      href: "/docs/concepts/meter",
      icon: "◔",
      accent: "#F59E0B",
    },
    {
      title: "Collect",
      description: "One shareable payment link: an agent pays over x402/USDC, a person pays via Pix, both verified before fulfillment. Early access.",
      href: "/docs/api/payment-links",
      icon: "⤺",
      accent: "#06B6D4",
    },
  ]}
/>

<DomainGrid
  title="You send agents out to spend."
  subtitle="The buy side: give an agent an allowance instead of an API key. It pays inside the cap you signed, and off-mission spend is refused before money moves."
  domains={[
    {
      title: "Wallet",
      description: "The agent's governed funds: multi-slot (BRL + USDC), non-custodial, one signed mandate over every slot. Dollars stay dollars, reais stay reais, no silent FX.",
      href: "/docs/concepts/wallets",
      icon: "▣",
      accent: "#3B82F6",
    },
    {
      title: "Pay",
      description: "One call, any rail: Pix, boleto, USDC over x402. Outbound spend, checked against the mandate server-side before any provider dispatch.",
      href: "/docs/concepts/meta-tools/pay",
      icon: "↗",
      accent: "#8B5CF6",
    },
    {
      title: "Shop",
      description: "Search a real store, drive its checkout, and pay the payable Pix from the wallet. The full buy loop, receipted end to end.",
      href: "/docs/concepts/meta-tools/shop",
      icon: "⌂",
      accent: "#F472B6",
    },
  ]}
/>

<DomainGrid
  title="The trust layer"
  subtitle="Both sides run on the same six primitives. They are not add-ons: every product above is a different door into the same governed runtime."
  domains={[
    {
      title: "Mandate",
      description: "Signed spending authority: cap, scope, expiry. A single signature authorizes the agent; everything outside it is refused.",
      href: "/docs/concepts/directed-pay",
      icon: "⊛",
      accent: "#3B82F6",
    },
    {
      title: "Receipt",
      description: "Every settlement closes with a hash-chained agentic receipt binding permission, settlement, and proof. Verifiable offline.",
      href: "/docs/concepts/audit-chain",
      icon: "⎘",
      accent: "#10B981",
    },
    {
      title: "Identity",
      description: "Know Your Agent: did:web + Ed25519 keys with a register, rotate, revoke lifecycle. Money moves only between known parties.",
      href: "/docs/concepts/agent-trust",
      icon: "◉",
      accent: "#F59E0B",
    },
    {
      title: "Guardrails",
      description: "Policy gates on every tool call: spend budgets, rate limits, human approval. Enforced server-side, never trusted to the model.",
      href: "/docs/concepts/guardrails",
      icon: "≠",
      accent: "#EF4444",
    },
    {
      title: "Audit",
      description: "An append-only, tamper-evident record of every tool call and money movement, exportable for compliance.",
      href: "/docs/concepts/audit-chain",
      icon: "≡",
      accent: "#8B5CF6",
    },
    {
      title: "Router",
      description: "One meta-tool call becomes the right provider call. Credentials are injected server-side; your agent never sees them.",
      href: "/docs/concepts/tool-router",
      icon: "⑃",
      accent: "#06B6D4",
    },
  ]}
/>

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

<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"
/>

### ↗ You send agents out to spend

<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"
/>

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

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.

```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 |
| **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:        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 15 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 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`](/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" |
| [`codespar_get_started`](/docs/concepts/meta-tools/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?" |

<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
- **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/sdk` on npm, with a single session model for all operations
- **Free tools**: [Check](/docs/check) (the Agent-Ready scan), the [sandbox](/docs/concepts/test-mode), the server [Catalog](/docs/servers), the [MCP Generator](/docs/mcp-generator), and the [SDK](/docs/api/sdk), [CLI](/docs/cli), and [MCP](/docs/providers/mcp) surfaces
- **Two environments**: `csk_test_` keys for sandbox with mock data, `csk_live_` for production

## Getting Started

<NextStepsGrid items={[
  { label: "SELL SIDE", title: "Quickstart: get paid", description: "Create a Gate paywall, curl the 402, take the first paid call, read the earnings.", href: "/docs/quickstart-seller" },
  { 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: "QUICKSTART", title: "Quickstart (SDK)", 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: "Gate", description: "The x402 gateway: paywall any API or MCP server, live on Base mainnet.", href: "/docs/concepts/gate" },
  { 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 15 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: "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" },
]} />