Frequently Asked Questions

General

What is CodeSpar?

CodeSpar is commerce infrastructure for AI agents in Latin America. It provides a unified SDK and API that gives AI agents (Claude, GPT, Gemini, or any LLM) the ability to process payments, issue invoices, ship packages, and send notifications through a catalog of integrated MCP servers covering every major LatAm commerce API. Think of it as "Stripe for AI agents" but covering the full commerce stack -- payments, fiscal, logistics, and messaging -- with deep Latin American coverage.

How is CodeSpar different from Composio or Toolhouse?

CodeSpar is purpose-built for commerce in Latin America. General-purpose tool platforms offer breadth across many domains. CodeSpar goes deep on a specific vertical:

• Regional payment methods: Native support for Pix, boleto, SPEI, OXXO, and installment plans
• Fiscal compliance: Automated NF-e, NFS-e, and CFDI issuance -- legally required in Brazil and Mexico
• A catalog of commerce-specific MCP servers across payments, fiscal, logistics, messaging, banking, ERP, and crypto -- 109+ servers and 2,200+ tools across 53 routing rails and six LATAM countries (BR, MX, AR, CO, CL, PE)
• 9 meta-tools that abstract provider routing -- your agent does not need to know about each provider's API
• Context window efficiency: 9 tool definitions instead of 50-100, saving thousands of tokens per request

What AI frameworks does CodeSpar support?

CodeSpar works with any AI framework through twelve official adapters (all at 0.4.0 with peerDependencies: { "@codespar/sdk": "^0.9.0" }), plus a direct HTTP API for any language:

You can also call the HTTP API directly from any language, or use the Python SDK (pip install codespar) for Python-native integrations.

Is CodeSpar open source?

The client-side SDK (@codespar/sdk) and all adapter packages are published on npm and open for inspection. The MCP server infrastructure, routing engine, and API backend are proprietary hosted services. The client libraries are designed to be transparent -- you can read the source to understand exactly what they do.

Can I use CodeSpar without an AI agent?

Yes. The SDK and API work independently of any AI framework. You can call session.execute() directly from your backend code without involving an LLM. This is useful for building traditional backend services that want the routing and provider abstraction benefits without the AI layer.

// No AI agent needed -- direct tool execution
const session = await codespar.create("user_123", { servers: ["stripe"] });
const result = await session.execute("codespar_pay", {
  method: "pix",
  amount: 5000,
  currency: "BRL",
});

Pricing

Is there a free plan?

Yes. Open Source is free forever: every MCP server and the SDK are MIT-licensed on npm. Self-host on your own infrastructure, no sign-up required, no usage caps. You only need a CodeSpar account when you want the managed orchestration layer (policy engine, HMAC mandates, payment router, audit ledger). See Pricing for the public tiers.

How does CodeSpar charge for the managed tier?

Orchestration bills per settled transaction -- $0.10 per money movement that reaches a terminal state (succeeded, refunded, or permanently failed after retries). Transactions that never settle (abandoned checkouts, cancelled holds) are free. Cross-border transactions add 0.5% of the converted amount on top of the $0.10. There is no minimum, no subscription, no per-tool-call fee. See Billing for the full breakdown.

What counts as a transaction?

A single movement of money through CodeSpar -- charge, payout, refund, transfer. Invoicing, shipping labels, WhatsApp messages, and ERP syncs are included in the transaction price. Issuing an NF-e for a Pix charge is one $0.10 tx, not two. See Billing.

How much does a typical workflow cost?

A standard e-commerce order that charges R$150 via Pix, issues an NF-e, creates a Correios label, and sends a WhatsApp confirmation is one settled transaction at $0.10. The fiscal, shipping, and messaging steps are included.

Are tool calls rate-limited?

Yes, but rate limits are not billing — they protect the managed runtime from abuse. Hit the limit and you get an HTTP 429; billing is untouched because only settled transactions settle. See Billing.

Do you offer custom Enterprise pricing?

Yes. Volume-based pricing, dedicated infrastructure, SSO/SAML, region pinning, and 24/7 support ship with Enterprise. Contact sales@codespar.dev.

Technical

What is a session?

A session is a scoped, authenticated connection to one or more MCP servers. It manages which tools your agent can access, handles server authentication using your stored credentials, and tracks usage for billing. Sessions expire after 30 minutes of inactivity.

What is the difference between execute, send, and sendStream?

Each underlying tool call (whether invoked directly or by the agent inside send/sendStream) is metered the same way -- see Billing.

What is the latency?

Tool call latency depends on the underlying provider API. Typical ranges:

NF-e issuance has the widest range because it communicates with SEFAZ in real time, and SEFAZ response times vary by state and time of day.

Are sandbox responses real?

No. When using a csk_test_ API key, all servers return mock data. No real payments are processed, no real invoices are issued, and no real messages are sent. The mock data is realistic, follows the same JSON schema as production responses, and includes valid-looking IDs, URLs, and timestamps. Use sandbox for development, testing, and demos.

What are meta-tools and why only 9?

Meta-tools are routing abstractions that sit in front of every connected provider-specific server. Instead of your agent needing to understand each provider's API, it calls one of 9 meta-tools (codespar_pay, codespar_charge, codespar_invoice, codespar_notify, codespar_ship, codespar_crypto_pay, codespar_kyc, codespar_discover, codespar_manage_connections), and CodeSpar routes to the appropriate provider across 53 routing rails.

The small surface is deliberate: it keeps the LLM's context window small (about 1,800 tokens for all nine tool definitions vs. 10,000-30,000 for raw server tools) and prevents the LLM from being overwhelmed by dozens of similar tools.

Can I access server-specific tools directly?

Yes. In addition to the 6 meta-tools, each connected MCP server exposes its native tools (e.g., stripe_create_subscription, mercadopago_create_preference). These are available through session.tools() and can be called via session.execute(). Use server-specific tools when you need features that meta-tools do not cover.

What happens if a provider is down?

If a provider API is unavailable, CodeSpar returns a 503 error (or the provider's own error code) in the tool result so your code can decide what to do. The payment router picks the provider at call time based on cost + settlement speed — it does not automatically retry on a different provider. To fall back, retry with an explicit provider field. The response always includes which provider handled the call.

Does CodeSpar support webhooks?

Yes — they are called triggers in CodeSpar. Register one via POST /v1/triggers (see the Triggers API) with a webhook URL and event filter. You receive signed HTTP callbacks when asynchronous events complete — payment confirmation, invoice authorization, shipping status changes, message delivery. Every CodeSpar → integrator payload is signed with X-CodeSpar-Signature using HMAC-SHA256 (hex-encoded) of the raw request body; verify against the signing secret returned once on trigger creation. Inbound webhooks (provider → CodeSpar) are verified per-provider with HMAC-SHA256, ECDSA P-256, HTTP Basic, or shared-secret comparison — the CodeSpar backend handles that, you don't see it.

What's the difference between codespar_pay and codespar_charge?

codespar_pay is outbound — it transfers money out of your account to a recipient (payouts, refunds, supplier disbursements). codespar_charge is inbound — it requests money from a buyer (Pix charge, card auth, boleto). They route to different rails: pay routes to Asaas / Mercado Pago for transfers; charge routes to Asaas / MP / iugu / Stone for Pix BRL and Stripe for card USD.

// Inbound: buyer pays merchant
await session.charge({ amount: 14900, currency: "BRL", method: "pix", ... });

// Outbound: merchant pays recipient
await session.execute("codespar_pay", { amount: 14900, currency: "BRL", recipient: { ... } });

Should I use polling or SSE for payment status?

Both work. Pick polling for one-off checks; pick SSE for long-running pending → settled flows where the user is waiting on the result.

// Polling — fine for one-off checks
const status = await session.paymentStatus(charge.tool_call_id);

// SSE — lower latency, single connection, auto-closes 5s after terminal state
await session.paymentStatusStream(charge.tool_call_id, {
  onUpdate: (s) => console.log(s.state),
});

The SSE stream sends a 15-second heartbeat to keep the connection alive and emits each state transition (pending → succeeded/failed) as it happens. Polling is simpler if you only need to check once after a webhook fires.

How do I issue an NF-e instead of an NFS-e?

codespar_invoice defaults to NFS-e (services), routed to municipal endpoints. For products, pass rail: "nfe" and CodeSpar routes to NFe.io.

await session.execute("codespar_invoice", {
  rail: "nfe",
  customer: { name: "...", document: "..." },
  items: [{ description: "...", amount: 14900, ncm: "...", cfop: "..." }],
});

NF-e issuance has additional operator setup compared to NFS-e: an A1 digital certificate, state tax registration (Inscrição Estadual), and an ICMS classification on each item. NFS-e only needs a municipal registration. CFDI MX (rail: "nfci", Facturapi) and Factura AR (AFIP) follow the same shape.

How do I add a new provider connection?

Operators add connections through the dashboard at /dashboard/connections — pick a provider, fill in the auth fields the modal asks for (api_key, OAuth flow, mTLS cert upload, HMAC signing secret, etc.), and the connection becomes available to every session in the project.

Agents discover what's already connected via session.connectionWizard(serverId), which returns the current connection status, the deep-link to the dashboard, and the required fields if the connection isn't set up yet.

const wiz = await session.connectionWizard("asaas");
if (wiz.current_status !== "connected") {
  console.log(`Operator must finish setup at ${wiz.dashboard_url}`);
}

What's idempotency_key and how do I correlate async settlements?

CodeSpar attaches a UUID-v4 idempotency_key to every outbound provider call. The provider stores it and echoes it back in webhook events as external_reference. The backend correlates idempotency_key ↔ external_reference to settle the originating tool_call_id, so you don't need to wire webhooks yourself — call paymentStatus (or stream) with the tool_call_id you got back from charge / pay:

const charge = await session.charge({ amount: 14900, currency: "BRL", method: "pix", ... });
const status = await session.paymentStatus(charge.tool_call_id);
// status.state, status.provider, status.external_reference, status.events

The same correlation works for codespar_kyc via verificationStatus(toolCallId) / verificationStatusStream(...).

Does CodeSpar work for crypto payments?

Yes. codespar_crypto_pay routes to Coinbase Commerce and Bitso. Operators connect Coinbase via API key and Bitso via the hmac_signed auth type (per-request signing).

Does CodeSpar do KYC?

Yes. codespar_kyc routes to Persona, Sift, Konduto, and Truora. Use verificationStatus(toolCallId) for one-off checks, or verificationStatusStream(toolCallId) to watch the inquiry settle. State priority: approved > rejected > review > expired > pending.

How do I connect a Brazilian bank with mTLS?

Brazilian open-banking APIs require mutual TLS. Operators upload the client certificate, private key, and CA bundle through the Provider Connect modal in /dashboard/connections; CodeSpar uses the cert auth type to establish the mTLS session with the upstream bank.

Banco do Brasil is the pilot today. Itaú, Santander, Bradesco, and Caixa are next batch — the plumbing is mechanical (catalog drop + a META_TOOL_CATALOG row), so there's no SDK change.

Coverage

Which countries are supported?

CodeSpar focuses on Latin America, with the deepest coverage in Brazil and Mexico:

Brazil has the most complete coverage across all categories. Mexico has strong payment and fiscal support. Other countries are expanding; check the Servers API for the latest catalog.

Which payment providers are supported?

12 payment providers across the region: Stripe, Mercado Pago, Asaas, PagSeguro, Pagarme, Conekta, Inter, Sicredi, and more. Each provider is wrapped as an MCP server with standardized tool definitions. See the full list via GET /v1/servers?category=payments.

Which fiscal systems are supported?

• Brazil: NF-e (goods), NFS-e (services), SPED (tax reporting), CT-e (transport), MDFe (freight manifest)
• Mexico: CFDI (all invoice types: ingreso, egreso, traslado)

All fiscal documents are generated in compliance with the respective tax authority's specifications (SEFAZ for Brazil, SAT for Mexico).

Can I request a new integration?

Yes. Email integrations@codespar.dev with the provider name, country, category, and your use case. Popular requests are prioritized. You can also check the public roadmap to see what integrations are planned.

Security

How are provider credentials stored?

Provider credentials (Stripe keys, OAuth tokens, digital certificates) are encrypted at rest using AES-256 and stored in isolated, access-controlled infrastructure. Credentials are decrypted only in memory at the moment of use and are never returned in API responses. When viewing auth configs in the dashboard, only the last 4 characters are shown.

Does CodeSpar see my customers' data?

CodeSpar processes data in transit to route tool calls to the correct provider. Customer data (names, emails, addresses, payment details) passes through CodeSpar's infrastructure but is not stored beyond what is needed to complete the tool call. Transaction metadata (tool name, timestamp, session ID) is retained for auditing and billing. Data retention follows each provider's policies.

Is CodeSpar SOC 2 compliant?

SOC 2 Type II certification is in progress. Contact security@codespar.dev for our current security documentation, including architecture diagrams, data flow documentation, and penetration test results.

How do I report a security vulnerability?

Email security@codespar.dev with details. We follow responsible disclosure practices and will respond within 24 hours. Do not open public GitHub issues for security vulnerabilities.

What authentication methods are supported?

Two mechanisms:

1. Bearer tokens (csk_live_ / csk_test_) -- Standard API key authentication for application-to-CodeSpar communication. See Authentication.
2. Service keys (cssk_internal_) -- Elevated server-to-server authentication with higher rate limits and cross-organization access. Used for trusted internal infrastructure.

Both key types can be scoped to specific permissions and rotated without downtime.

Open Source

What parts of CodeSpar are open source?

The client-side packages are published on npm and PyPI and available for inspection:

The backend API, MCP server infrastructure, routing engine, and provider integrations are proprietary hosted services.

Can I self-host CodeSpar?

The MCP servers and SDK are MIT-licensed and can be self-hosted — that is the Open Source tier. The managed orchestration layer (policy engine, HMAC mandates, payment router, audit ledger) is currently hosted-only; a self-hosted Enterprise option is available on request for customers with specific compliance requirements. Contact sales@codespar.dev.

How do I contribute?

The client libraries accept contributions. File issues or pull requests on GitHub. For the hosted service, submit feature requests and integration requests through the dashboard or via email.