---
title: Cookbooks
description: 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.
---

import { Callout } from "fumadocs-ui/components/callout";

# Cookbooks

<VersionBadge pkg="@codespar/sdk" />

Every cookbook is a **runnable example** — not pseudo-code. Copy the file, fill in your API key, and run it.

<Callout type="info">
Cookbooks are runnable examples — copy the file, fill in your API key, and run. Use the `csk_test_*` key auto-minted at signup (or mint another at [Dashboard → API Keys](https://codespar.dev/dashboard/api-keys)) — it resolves to a `test` project where the runtime routes to provider sandboxes via operator-funded shared connections, so the cookbook runs end-to-end without provider OAuth and without real-money side effects. For fully deterministic output that doesn't hit any upstream, declare per-session fixtures via `cs.create({ mocks: {...} })` — see [Test Mode](/docs/concepts/test-mode) for the strict-mode contract and envelope reference.
</Callout>

---

## Your agent buys

Buy-side recipes: the agent is the spender, moving money out of a wallet or account it governs under a mandate.

<NextStepsGrid items={[
  { label: "COOKBOOK", title: "Shopping Agent", description: "The full buy-side loop: search a real store, start the checkout session, poll to the payable Pix, and settle it from the governed wallet under a mandate.", href: "/docs/cookbooks/shopping-agent" },
  { label: "COOKBOOK", title: "Agent Card", description: "Issue a governed virtual card an agent can spend with: every authorization checked against the mandate server-side, freeze or cancel on demand.", href: "/docs/cookbooks/agent-card" },
  { label: "COOKBOOK", title: "Agent with a Wallet", description: "End-to-end walkthrough of Programmable Wallets: create a wallet, bind a funding source, fund via sandbox Pix, execute a mandate-gated payment, watch the audit trail render.", href: "/docs/cookbooks/agent-with-wallet" },
  { label: "COOKBOOK", title: "Crypto Pay Agent", description: "Generate a stablecoin payment URL via codespar_crypto_pay, share it with the user, and watch for settlement via webhook or paymentStatus.", href: "/docs/cookbooks/crypto-pay-agent" },
  { label: "COOKBOOK", title: "Bulk Refund", description: "Refund a batch of payments in parallel using session.loop(). Handle partial failures without aborting the whole run.", href: "/docs/cookbooks/bulk-refund" },
  { label: "COOKBOOK", title: "Multi-Provider Routing", description: "Route payments across Stripe, Asaas, and Mercado Pago automatically. The agent calls codespar_pay — CodeSpar picks the best provider for each transaction.", href: "/docs/cookbooks/multi-provider" },
]} />

## Your agent sells

Sell-side recipes: the agent is the merchant, collecting from, invoicing, shipping to, or verifying a counterparty.

<NextStepsGrid items={[
  { label: "COOKBOOK", title: "Pix Payment Agent", description: "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.", href: "/docs/cookbooks/pix-payment-agent" },
  { label: "COOKBOOK", title: "E-Commerce Checkout", description: "Build an AI-powered checkout flow that handles product discovery, payment, invoicing, and shipping — in a single conversation.", href: "/docs/cookbooks/ecommerce-checkout" },
  { label: "COOKBOOK", title: "Marketplace Payout", description: "Split a marketplace transaction into platform fee + seller payout. One agent, two settled transactions, full audit trail.", href: "/docs/cookbooks/marketplace-payout" },
  { label: "COOKBOOK", title: "Cross-Border Fintech", description: "Accept a USD card charge, settle to a BRL account, issue the fiscal document. One transaction, explicit FX surcharge, LGPD-ready audit trail.", href: "/docs/cookbooks/cross-border-fintech" },
  { label: "COOKBOOK", title: "Webhook Listener", description: "React to payment webhooks with a deterministic loop. On payment.confirmed, automatically issue an NF-e, create shipping, and send WhatsApp — no agent, no LLM, no surprise.", href: "/docs/cookbooks/webhook-listener" },
  { label: "COOKBOOK", title: "KYC Agent", description: "Gate high-value transactions on identity verification. The agent fires codespar_kyc, polls or streams verificationStatus, then routes to the approved or rejected branch.", href: "/docs/cookbooks/kyc-agent" },
]} />

## Architecture patterns (both sides)

Patterns that apply whether your agent buys or sells.

<NextStepsGrid items={[
  { label: "COOKBOOK", title: "Ledger Agent", description: "The agent keeps the books: double-entry journal entries on every commerce event, balance reads, and the signed agentic receipts (mandate to payment to delivery) for reconciliation.", href: "/docs/cookbooks/ledger-agent" },
  { label: "COOKBOOK", title: "Multi-Tenant SaaS", description: "Each customer runs their own agent with their own providers and credentials. Sessions are scoped per tenant — isolated by design, metered per tenant for billing.", href: "/docs/cookbooks/multi-tenant" },
  { label: "COOKBOOK", title: "Streaming Chat Agent", description: "Real-time commerce chat with token-by-token streaming. Next.js App Router + Vercel AI SDK. Tool calls appear in the UI as they happen.", href: "/docs/cookbooks/streaming-chat" },
  { label: "COOKBOOK", title: "Webhook Providers Reference", description: "Per-provider inbound webhook signature schemes: HMAC-SHA256, ECDSA P-256, HTTP Basic, shared-secret. For self-hosters and operators verifying provider events.", href: "/docs/cookbooks/webhook-providers" },
]} />

---

## How the cookbooks are structured

Every cookbook follows the same shape so you can skim one and jump to any other.

1. **The scenario.** A one-paragraph problem statement — who the user is, what they want, what constraints apply.
2. **The code.** A single file, fully typed, no dependencies beyond `@codespar/sdk` and what the scenario actually needs.
3. **Walkthrough.** Why each part exists. What would break if you changed it.
4. **Test run.** Exact CLI commands to execute the cookbook against sandbox and what the output looks like.
5. **Production checklist.** What to change before you ship. Usually: environment, API key prefix, error handling for the failure mode that matters for that flow.

## Build your own

Missing a scenario? All cookbooks live in `content/docs/cookbooks/*.mdx` in this repo. Click **"Edit this page on GitHub"** on any cookbook to contribute.

## Next steps

<NextStepsGrid items={[
  { label: "QUICKSTART", title: "5-minute quickstart", description: "Before the cookbooks — install the SDK and get your first session running.", href: "/docs/quickstart" },
  { label: "CONCEPT", title: "Test Mode", description: "Inline mocks and the strict-mode contract — the cleanest way to keep a cookbook deterministic.", href: "/docs/concepts/test-mode" },
  { label: "CONCEPT", title: "Sessions", description: "The primitive all cookbooks build on.", href: "/docs/concepts/sessions" },
  { label: "CONCEPT", title: "Triggers", description: "For the webhook-listener cookbook — signed HTTP callbacks on settled events.", href: "/docs/concepts/triggers" },
  { label: "REFERENCE", title: "SDK Reference", description: "Every method, type, and signature used across the cookbooks.", href: "/docs/api/sdk" },
]} />