Docs/Quickstart

Quickstart

Install the SDK, create a session, and execute your first commerce tool call in under 5 minutes.

Prerequisites: Node.js 20+, an API key (free — create an account and go to Settings → API Keys).

Install the SDK

Pick your framework and install the matching adapter:

Claude

npm install @codespar/sdk @codespar/claude @anthropic-ai/sdk

OpenAI

npm install @codespar/sdk @codespar/openai openai

Vercel AI SDK

npm install @codespar/sdk @codespar/vercel ai @ai-sdk/openai

Python (PyPI)

pip install codespar

Configure your API key

Set your CodeSpar API key in your environment:

.env

CODESPAR_API_KEY=csk_live_your_key_here

Get your key from the dashboard. Keys start with csk_live_ for production or csk_test_ for testing.

Create a session

A session scopes tools, auth, and billing to a user. Create one per user interaction:

agent.ts

import { CodeSpar } from "@codespar/sdk";

const cs = new CodeSpar(); // reads CODESPAR_API_KEY from env

const session = await cs.create("user_123", {
  preset: "brazilian", // enables Pix, NF-e, Melhor Envio, WhatsApp, Omie
});

console.log("Session created:", session.id);
console.log("Servers:", session.servers); // ["zoop", "nuvem-fiscal", ...]

Execute a tool call

Call a commerce tool directly:

agent.ts

const result = await session.execute("codespar_pay", {
  amount: 150,
  currency: "BRL",
  method: "pix",
  recipient: "customer@email.com",
  description: "Order #1234",
});

console.log(result.success);  // true
console.log(result.data);     // { transaction_id: "txn_...", status: "approved", pix_qr_code: "..." }
console.log(result.duration);  // 127 (ms)

Every tool call is logged on the backend with input, output, and duration — the billing unit for metered plans.

Use with your AI framework

Pass CodeSpar tools to your preferred AI framework. Here's Claude:

claude-agent.ts

import { CodeSpar } from "@codespar/sdk";
import { getTools, handleToolUse, toToolResultBlock } from "@codespar/claude";
import Anthropic from "@anthropic-ai/sdk";

const cs = new CodeSpar();
const session = await cs.create("user_123", { preset: "brazilian" });
const tools = await getTools(session);

const claude = new Anthropic();
const response = await claude.messages.create({
  model: "claude-sonnet-4-5-20250514",
  max_tokens: 1024,
  tools,
  messages: [{ role: "user", content: "Charge R$150 via Pix" }],
});

// Handle tool calls
for (const block of response.content) {
  if (block.type === "tool_use") {
    const result = await handleToolUse(session, block);
    console.log(result.data);
  }
}

See the full provider guides: Claude · OpenAI · Vercel AI SDK

Try the Sandbox

Don't want to write code yet? Try the Sandbox — a playground where you can chat with a commerce agent and see tool calls execute in real time. Type "Charge R$500 via Pix and issue the NF-e" to see the Complete Loop in action.

What's next?

→ How CodeSpar works (sessions, meta-tools, Complete Loop)→ Tools & meta-tools reference → Authentication & provider auth → The Complete Loop deep dive (blog)