# CodeSpar > The agentic operating system for money movement in Latin America. Commerce is the wedge; money movement is the platform. ## What is CodeSpar? CodeSpar is the runtime that lets AI agents move money across Latin America: commerce checkout, procurement, payroll, treasury and cross-border, over the rails the region actually uses (Pix, boleto, NF-e, WhatsApp, SPEI). One SDK and one MCP server give an agent payments, invoicing, shipping, notifications and ERP reconciliation, governed by signed mandates and an immutable audit ledger, without integrating dozens of regional APIs. ## Install in your AI agent (MCP) Give any AI agent a Latin-American commerce rail in one step — add the codespar MCP server. No code: - Command: `npx -y @codespar/mcp serve` - Env var: `CODESPAR_API_KEY` = your key (`csk_test_…` for the sandbox, `csk_live_…` for production) - Tools exposed, by side: BUY (the agent spends under a signed mandate): codespar_shop, codespar_wallet, codespar_pay, codespar_crypto_pay, codespar_issue · SELL (the agent collects as merchant): codespar_checkout, codespar_charge, codespar_invoice, codespar_ship, codespar_notify, codespar_kyc · SHARED: codespar_ledger, codespar_discover, codespar_manage_connections - Buyer-agent quickstart (MCP-first, no code): https://docs.codespar.dev/docs/quickstart-buyer Per-host install (full guide: https://codespar.dev/agents): - Claude Code: `claude mcp add codespar --env CODESPAR_API_KEY=… -- npx -y @codespar/mcp serve` - Codex CLI: `codex mcp add codespar --env CODESPAR_API_KEY=… -- npx -y @codespar/mcp serve` - Cursor / VS Code: one-click install buttons at https://codespar.dev/agents - Claude Desktop: add the block above to the `mcpServers` object in claude_desktop_config.json - Frameworks (LangChain, CrewAI, Vercel AI, OpenAI, LlamaIndex, Mastra, AutoGen, CAMEL, Letta, Google GenAI): `npm install @codespar/ @codespar/sdk`, then `getTools(session)` Hosted remote MCP (no local process, MCP Streamable HTTP): - URL: `https://connect.codespar.dev/mcp` - Auth: header `Authorization: Bearer `, or the OAuth 2.1 flow advertised at https://connect.codespar.dev/.well-known/oauth-protected-resource - Claude Code (remote): `claude mcp add --transport http codespar https://connect.codespar.dev/mcp --header "Authorization: Bearer "` - Same 14 meta-tools, same mandate governance and audit as the stdio server ## MCP Server Catalog Beyond the meta-tools above, CodeSpar publishes 125+ individual MCP servers, one per LATAM provider, each on npm as `@codespar/mcp-`; 126 of them are live in the official MCP Registry. Categories: payments, fiscal, logistics, messaging, banking, ERP, e-commerce, crypto, identity/KYC, fraud/risk, data, agentic protocols. Exact current count: https://codespar.dev/api/servers. - Machine-readable catalog (JSON, exact count + every server): https://codespar.dev/api/servers - Browse: https://codespar.dev/servers - Sitemap (every server detail page, all locales): https://codespar.dev/sitemap.xml - Install any one directly: `npx -y @codespar/mcp-` (e.g. `npx -y @codespar/mcp-zoop`) ## Agent discovery - Agent manifest (JSON: capabilities, install, and safety model): https://codespar.dev/.well-known/agent-metadata.json - Quickstart by intent (JSON): https://codespar.dev/api/quickstart?intent=payments (also: fiscal, logistics, commerce, crypto) ## Agent trust (Know Your Agent) Every agent gets a verifiable identity (W3C did:web + Ed25519) that is separate from its authorization (a scoped, expiring, revocable mandate). One agent can verify another agent's identity and reputation with no CodeSpar credential. - Overview: https://codespar.dev/trust - Docs: https://docs.codespar.dev/docs/concepts/agent-trust - Public verification endpoints (no auth, base https://api.codespar.dev): - `GET /v1/agents/:did` returns status, non-revoked keys, and the KYC boolean (never the raw CPF/CNPJ) - `GET /v1/agents/:did/did.json` returns the did:web document (Ed25519 public keys) - `GET /v1/agents/:did/reputation` returns an issuer-signed reputation attestation, derived from the audit chain, not self-asserted - `GET /v1/agents/:did/erc8004` returns an ERC-8004 style export (identity + reputation + validation) - Verifiable mandate: a spend authorization carries an Ed25519 agent signature over a canonical string; a counterparty verifies it offline with the public key from did.json, no call to CodeSpar. - Facilitator (authed): `POST /v1/facilitator/x402/executions` ingests an externally-signed x402 (EIP-3009) authorization, verifies the foreign signature, translates it onto an internal mandate, runs the cap gate, settles, and seals a receipt. Settlement runs on testnet rails today; production settlement is environment-gated. Docs: https://docs.codespar.dev/docs/concepts/facilitator ## SDK - Package: `@codespar/sdk` (npm) - Base URL: `https://api.codespar.dev` - Auth: API key via `CODESPAR_API_KEY` - OpenAPI (machine-readable schema; partial coverage today, expanding): https://codespar.dev/openapi.json ## Quick Start ```typescript import { CodeSpar } from "@codespar/sdk"; const cs = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY }); const session = await cs.create("user_123", { preset: "brazilian" }); const tools = await session.tools(); ``` ## Provider Adapters - `@codespar/claude` — Anthropic Claude - `@codespar/openai` — OpenAI GPT - `@codespar/vercel` — Vercel AI SDK - `@codespar/langchain` — LangChain.js - `@codespar/google-genai` — Google Gemini - `@codespar/mastra` — Mastra - `@codespar/crewai` — CrewAI - `@codespar/autogen` — Microsoft AutoGen - `@codespar/llama-index` — LlamaIndex.TS - `@codespar/letta` — Letta (MemGPT) - `@codespar/camel` — CAMEL-AI - `@codespar/mcp` — MCP (Claude Desktop, Cursor) ## Core Concepts - **Session**: A scoped connection to one or more commerce servers. Create → use tools → close. - **Tools**: JSON Schema functions your agent calls. Routed through MCP servers. - **Meta-tools**: built-in tools (discover, shop, wallet, pay, charge, checkout, invoice, ship, notify, crypto_pay, issue, ledger, kyc, manage_connections) that route to the right LATAM provider. - **Complete Loop**: Multi-step workflows via `session.loop()`. - **Billing**: Pay per tool call. No session fees. ## Documentation - Docs: https://docs.codespar.dev - GitHub: https://github.com/codespar/codespar-core - Dashboard: https://codespar.dev/dashboard ## Documentation map Every docs page, grouped. Raw markdown for any page: replace the host path with /api/docs-md/ on codespar.dev. ### Getting started - [Build Your Own Server](https://docs.codespar.dev/docs/build-your-own) — Create a custom MCP server that integrates with CodeSpar's session model, billing, and tool routing. - [Changelog](https://docs.codespar.dev/docs/changelog) — Release history for the CodeSpar SDK, adapters, and MCP servers. - [Check](https://docs.codespar.dev/docs/check) — Free Agent-Ready scan. 12 public checks that tell you whether AI agents can find, read, and buy from your site, with an evidence URL for every finding and a shareable report. - [CLI](https://docs.codespar.dev/docs/cli) — The codespar CLI — authenticate, list servers, execute tools, manage connections, and scaffold projects from your terminal. - [Debugging](https://docs.codespar.dev/docs/debugging) — Debug tool calls, inspect execution logs, and monitor agent performance with CodeSpar's built-in observability. - [Error Reference](https://docs.codespar.dev/docs/errors) — Every error code the CodeSpar API can return, with HTTP status, the response shape, when it fires, and the fix. Aggregated across sessions, projects, connections, triggers, wallets, and auth surfaces. - [FAQ](https://docs.codespar.dev/docs/faq) — Frequently asked questions about CodeSpar -- pricing, capabilities, supported countries, security, technical details, and open source. - [Glossary](https://docs.codespar.dev/docs/glossary) — Definitions for key terms and concepts used throughout the CodeSpar documentation. - [How CodeSpar Works](https://docs.codespar.dev/docs/how-it-works) — Understand how CodeSpar connects your AI agent to every major LatAm commerce API through sessions, meta-tools, and MCP servers. - [MCP Generator](https://docs.codespar.dev/docs/mcp-generator) — Automatically generate MCP server code from your existing API endpoints using CodeSpar's scanner and generator. - [Quickstart](https://docs.codespar.dev/docs/quickstart) — Get your first AI agent commerce interaction running in under 5 minutes. - [Quickstart (Buyer agent)](https://docs.codespar.dev/docs/quickstart-buyer) — Give your coding agent the power to shop and pay in Brazil — MCP-first, no code. Search a real store, hold a governed wallet, pay under a signed mandate. - [Quickstart (Python)](https://docs.codespar.dev/docs/quickstart-python) — Get a CodeSpar commerce agent running in Python — sync for scripts and Django, async for FastAPI and LangChain. Under 5 minutes. - [Quickstart: get paid](https://docs.codespar.dev/docs/quickstart-seller) — Put an x402 paywall in front of your API and take the first paid call in five minutes. - [Servers & Toolkits](https://docs.codespar.dev/docs/servers) — Browse CodeSpar's catalog of MCP servers across payments, fiscal, logistics, messaging, banking, ERP, crypto, and agentic commerce in Latin America. ### Concepts - [Agent identity and trust (KYA)](https://docs.codespar.dev/docs/concepts/agent-trust) — Verifiable agent identity (did:web + Ed25519), signed reputation, and the register / rotate / revoke key lifecycle. Know Your Agent for the money side. - [Audit chain](https://docs.codespar.dev/docs/concepts/audit-chain) — An append-only, hash-chained record of every tool call and money movement. Exactly-once, tamper-evident, and exportable for compliance. - [Authentication](https://docs.codespar.dev/docs/concepts/authentication) — API key management, service authentication, key rotation, and security best practices for the CodeSpar API. - [Billing](https://docs.codespar.dev/docs/concepts/billing) — Per-settled-transaction pricing, plans, usage tracking, and Stripe-powered billing for CodeSpar. - [Connect Links](https://docs.codespar.dev/docs/concepts/connect-links) — Hosted OAuth flow that lets your end users connect their own Stripe, Mercado Pago, Shopify, and other provider accounts, without you building or maintaining a connection UI. - [Directed-pay](https://docs.codespar.dev/docs/concepts/directed-pay) — Consumer-mandate flow — accounts charge an end-consumer's rail (Pix consent, card token, TED debit-auth) under a signed, capped, revocable consent. The non-wallet half of the governed commerce primitives. - [Facilitator](https://docs.codespar.dev/docs/concepts/facilitator) — Ingest an externally-signed x402 (EIP-3009) authorization, verify it, translate it onto an internal mandate, execute it under the cap gate, and seal a receipt. - [Gate](https://docs.codespar.dev/docs/concepts/gate) — Gate is the x402 gateway. Put an x402 paywall in front of any API or MCP server and get paid in USDC on Base. Share a gateway URL, charge agents per call, no signup, no card, no session. - [Guardrails](https://docs.codespar.dev/docs/concepts/guardrails) — The policy layer that gates every agent tool call before it dispatches, spend budgets, rate limits, and human approval, enforced server-side. - [Meter](https://docs.codespar.dev/docs/concepts/meter) — Post-paid metered pricing on a Gate paywall. The buyer signs a spending ceiling once, your upstream reports the actual work in a response header, and the difference is refunded on-chain automatically. - [Pay to Agent](https://docs.codespar.dev/docs/concepts/pay-to-agent) — Pay another agent by Agent ID instead of a raw address. The recipient must be a registered, non-revoked identity — never an anonymous wallet. Payouts, splits, and tips over USDC on Base mainnet. - [Projects](https://docs.codespar.dev/docs/concepts/projects) — Projects are the second level of CodeSpar's 2-level tenancy model -- an isolation boundary inside an account for API keys, connections, triggers, sessions, and events. - [Sessions](https://docs.codespar.dev/docs/concepts/sessions) — Sessions are scoped connections to MCP servers that manage tool access, authentication, and usage tracking for AI agent commerce operations. - [Shopper Identity](https://docs.codespar.dev/docs/concepts/shopper-identity) — Connect-once + vaulted shopper identity — let a shopper connect a login-walled store once, or vault a guest-checkout profile, so an agent can buy on their behalf without re-asking. Per-consumer, inbound, credentials never exposed. - [Test Mode](https://docs.codespar.dev/docs/concepts/test-mode) — Hosted test mode lets you run an agent against the CodeSpar runtime with inline mock declarations — deterministic responses, no provider OAuth, full Guardrails governance. Declare mocks at session create; assert on the round-trip in your tests. - [Tool Router](https://docs.codespar.dev/docs/concepts/tool-router) — Route tool calls and raw HTTP requests through a managed session. Auth is injected server-side, so your agent never touches provider credentials. - [Tools & Meta-Tools](https://docs.codespar.dev/docs/concepts/tools) — CodeSpar provides 15 meta-tools that abstract every connected MCP server into a unified commerce interface, reducing context window cost and simplifying agent development. - [Triggers](https://docs.codespar.dev/docs/concepts/triggers) — Triggers are CodeSpar's outbound webhook subscriptions. Your app receives signed HTTP callbacks when asynchronous events settle (payment succeeded, invoice issued, notification delivered) or when the platform itself changes state. - [Wallets](https://docs.codespar.dev/docs/concepts/wallets) — Programmable wallets — per-agent fund pools with mandate-gated debits, multi-rail funding (Pix, TED, USD wire, USDC, BRLA), and automatic reconciliation. Governed by Guardrails in the managed tier. ### Meta-tools (by side: see the tool list above) - [codespar_charge](https://docs.codespar.dev/docs/concepts/meta-tools/charge) — Inbound charges — buyer pays merchant. 19 provider rails — Pix/boleto/card/wallet across BR, MX, PE, CO, CL, AR + USD. Async settlement, uniform payload. - [codespar_checkout](https://docs.codespar.dev/docs/concepts/meta-tools/checkout) — Sell-side merchant checkout — as a merchant, create and process a checkout for a shopper to pay you. Routes to Stripe ACP, Asaas, or x402 by payment method. Call via session.execute(). - [codespar_crypto_pay](https://docs.codespar.dev/docs/concepts/meta-tools/crypto-pay) — Crypto-rail payments — stablecoin checkout on Coinbase Commerce, BR rails on Bitso and Foxbit, and cross-border payout via our on/offramp partner. - [codespar_discover](https://docs.codespar.dev/docs/concepts/meta-tools/discover) — Semantic + lexical tool search. pgvector text-embedding-3-small + pg_trgm fallback, with connection bias toward providers the session can already reach. - [codespar_get_started](https://docs.codespar.dev/docs/concepts/meta-tools/get-started) — Read-only setup planner. Returns the ordered happy path for the authenticated workspace, covering which rails are already connected, what to connect next, and the first calls to try. Moves no money. - [codespar_invoice](https://docs.codespar.dev/docs/concepts/meta-tools/invoice) — Fiscal invoices. Default rail NFS-e; opt into NF-e for products, CFDI for Mexico, Factura AR for Argentina. - [codespar_issue](https://docs.codespar.dev/docs/concepts/meta-tools/issue) — Issue and control payment cards for AI agents or end-users. Virtual + physical cards, freeze/unfreeze/cancel. Routes to our card-issuing partner (pan-LATAM issuing). Typed wrapper session.issue(args). - [codespar_kyc](https://docs.codespar.dev/docs/concepts/meta-tools/kyc) — Identity verification. Persona (default INTL), Sift (fraud-score), Konduto (BR fraud), Truora (LATAM-wide). Async — track via verificationStatus. - [codespar_ledger](https://docs.codespar.dev/docs/concepts/meta-tools/ledger) — Double-entry ledger — record money movement, read balances, create accounts. Routes to the tenant's self-hosted Lerian Midaz. Typed wrapper session.ledger(args). - [codespar_manage_connections](https://docs.codespar.dev/docs/concepts/meta-tools/manage-connections) — Connection wizard backend. List, status, and initiate operations let an agent introspect connections and surface a connect-URL when a provider is missing. - [codespar_notify](https://docs.codespar.dev/docs/concepts/meta-tools/notify) — Messaging meta-tool. WhatsApp BR via Z-API; SMS / email USD via Twilio + SendGrid; WhatsApp INTL via Twilio. - [codespar_pay](https://docs.codespar.dev/docs/concepts/meta-tools/pay) — Outbound spend. Money leaves the wallet or account your agent governs. 26 provider rails across BR (incl. 9 banks direct via mTLS), MX, PE, CL, CO, and international card/wire. - [codespar_ship](https://docs.codespar.dev/docs/concepts/meta-tools/ship) — Domestic shipping. Three rails on Melhor Envio — domestic-label, domestic-quote, domestic-track. Typed wrapper session.ship(args). - [codespar_shop](https://docs.codespar.dev/docs/concepts/meta-tools/shop) — Buy-side shopping — act as the shopper to search a store's catalog and buy a product, minting the store's real Pix. VTEX guest checkout and Mercado Livre. Call via session.execute(). - [codespar_wallet](https://docs.codespar.dev/docs/concepts/meta-tools/wallet) — The agent's governed funds — check balance and Pix key, read the wallet ledger, mint a Pix copia-e-cola to top up. Buy-side companion to codespar_pay. ### API reference - [@codespar/api-types](https://docs.codespar.dev/docs/api/api-types) — Zod schemas + TypeScript types for every /v1/* REST shape on api.codespar.dev. Used internally by the SDK and dashboard; published for callers building HTTP clients directly. - [Connections API](https://docs.codespar.dev/docs/api/connections) — HTTP API reference for provider connections — create and rotate credentials, list and inspect connections, revoke, and manage per-connection merchant config. - [Payment Links API](https://docs.codespar.dev/docs/api/payment-links) — HTTP API reference for Collect payment links. Shareable pay URLs where an agent pays over x402/USDC or a person pays via Pix, verified before fulfillment. - [Paywalls API](https://docs.codespar.dev/docs/api/paywalls) — HTTP API reference for Gate. Create and manage x402 paywalls that charge agents per call, and read per-paywall earnings. - [Projects API](https://docs.codespar.dev/docs/api/projects) — HTTP API reference for creating, listing, updating, and deleting projects -- the second level of CodeSpar's account -> project tenancy model. - [SDK Reference](https://docs.codespar.dev/docs/api/sdk) — Complete TypeScript reference for @codespar/sdk — classes, interfaces, methods, and types. - [Servers API](https://docs.codespar.dev/docs/api/servers) — HTTP API reference for browsing and filtering CodeSpar's catalog of MCP servers across payments, fiscal, logistics, messaging, banking, ERP, and crypto. - [Sessions API](https://docs.codespar.dev/docs/api/sessions) — Complete HTTP API reference for creating, managing, and interacting with CodeSpar sessions, including tool execution, connection management, async settlement status, and streaming. - [Tools API](https://docs.codespar.dev/docs/api/tools) — HTTP API reference for listing, searching, and inspecting tool definitions available in a CodeSpar session. - [Triggers API](https://docs.codespar.dev/docs/api/triggers) — HTTP API for creating, managing, and inspecting CodeSpar triggers, the outbound webhook subscriptions with signed deliveries, retries, and a dead-letter queue. - [Wallets API](https://docs.codespar.dev/docs/api/wallets) — HTTP API reference for Programmable Wallets — create wallets, post ledger entries, bind funding sources, execute mandate-gated payments, triage reconciliation anomalies. ### Cookbooks (recipes) - [Agent with a Wallet](https://docs.codespar.dev/docs/cookbooks/agent-with-wallet) — End-to-end walkthrough of Programmable Wallets — create a wallet, bind an Asaas funding source, fund via sandbox Pix, execute a mandate-gated payment, watch the audit trail render. ~15 minutes. - [Crypto Pay Agent](https://docs.codespar.dev/docs/cookbooks/crypto-pay-agent) — Generate a stablecoin payment URL via codespar_crypto_pay (Coinbase Commerce default), share with the user, watch for settlement webhook or paymentStatus. - [E-Commerce Checkout](https://docs.codespar.dev/docs/cookbooks/ecommerce-checkout) — Brazilian e-commerce flow — buyer pays via Pix, NF-e gets issued, label generated, customer notified on WhatsApp. Same shape that ships in codespar-core/examples/brazilian-ecommerce. - [Cookbooks](https://docs.codespar.dev/docs/cookbooks/index) — End-to-end recipes you can copy into production. Each cookbook is a small working agent that solves one real commerce problem, wired through the CodeSpar SDK. - [Marketplace Payout](https://docs.codespar.dev/docs/cookbooks/marketplace-payout) — Split a marketplace transaction into platform fee + seller payout. One agent, two settled transactions, full audit trail. - [Multi-Tenant Agent](https://docs.codespar.dev/docs/cookbooks/multi-tenant) — Build a SaaS where each customer runs their own commerce agent with their own providers and credentials. Sessions are scoped per tenant — isolated by design, metered per tenant for billing. - [Pix Payment Agent](https://docs.codespar.dev/docs/cookbooks/pix-payment-agent) — The simplest agent you can build with CodeSpar. Create a Pix charge, generate a QR code, and send it to the customer via WhatsApp — in ~50 lines of code. - [Shopping Agent](https://docs.codespar.dev/docs/cookbooks/shopping-agent) — A buy-side agent that searches a real store, drives the store's checkout, and pays the resulting Pix from its governed wallet under a signed mandate. - [Webhook Listener](https://docs.codespar.dev/docs/cookbooks/webhook-listener) — React to payment webhooks with a deterministic loop. On commerce.payment.succeeded, automatically issue an NF-e, create shipping, and send WhatsApp. No agent, no LLM, no surprise. - [Webhook Providers Reference](https://docs.codespar.dev/docs/cookbooks/webhook-providers) — Per-provider inbound webhook signature schemes — HMAC-SHA256, ECDSA P-256, HTTP Basic, shared-secret. For self-hosters and operators verifying provider events. ### Framework adapters and MCP - [AutoGen](https://docs.codespar.dev/docs/providers/autogen) — Use @codespar/autogen to give Microsoft AutoGen agents commerce capabilities in Latin America. - [CAMEL-AI](https://docs.codespar.dev/docs/providers/camel) — Use @codespar/camel to give CAMEL-AI role-playing agents commerce capabilities in Latin America. - [Claude](https://docs.codespar.dev/docs/providers/claude) — Use @codespar/claude to give Anthropic Claude agents commerce capabilities in Latin America. - [CrewAI](https://docs.codespar.dev/docs/providers/crewai) — Use @codespar/crewai to give CrewAI agent crews commerce capabilities in Latin America. - [Google Gemini](https://docs.codespar.dev/docs/providers/google-genai) — Use @codespar/google-genai to give Google Gemini agents commerce capabilities in Latin America. - [Hermes](https://docs.codespar.dev/docs/providers/hermes) — Use @codespar/hermes to give Hermes Agent (Nous Research) a LATAM commerce rail. - [Provider Adapters](https://docs.codespar.dev/docs/providers/index) — Drop-in adapters that wire CodeSpar sessions into your existing agent framework — Claude, OpenAI, Vercel AI SDK, LangChain, Mastra, and 6 more. - [LangChain](https://docs.codespar.dev/docs/providers/langchain) — Use @codespar/langchain to give LangChain.js agents commerce capabilities in Latin America. - [Letta](https://docs.codespar.dev/docs/providers/letta) — Use @codespar/letta to give Letta (MemGPT) agents commerce capabilities in Latin America. - [LlamaIndex](https://docs.codespar.dev/docs/providers/llama-index) — Use @codespar/llama-index to give LlamaIndex.TS agents commerce capabilities in Latin America. - [Mastra](https://docs.codespar.dev/docs/providers/mastra) — Use @codespar/mastra to give Mastra agents commerce capabilities in Latin America. - [MCP](https://docs.codespar.dev/docs/providers/mcp) — Use @codespar/mcp to connect CodeSpar tools to Claude Desktop, Cursor, and other MCP-compatible clients. - [OpenAI](https://docs.codespar.dev/docs/providers/openai) — Use @codespar/openai to give GPT agents commerce capabilities in Latin America. - [Vercel AI SDK](https://docs.codespar.dev/docs/providers/vercel) — Use @codespar/vercel to integrate CodeSpar tools with the Vercel AI SDK for streaming agent interactions.