---
title: Cookbooks
description: Nineteen runnable recipes. Each one is a working agent that solves one real commerce problem end to end, with the refusals you will actually hit.
---

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

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

Every cookbook is a **single runnable file**, not pseudo-code. Copy it, put your `csk_test_` key in the environment, and run it: a test key resolves to a sandbox project, so the whole flow completes without provider OAuth and without moving real money.

Each one also documents the order its handlers run in, what already exists when a refusal arrives, and which refusal a retry can fix. That is usually the part you need at 2am.

## Start here

<NextStepsGrid items={[
  { label: "COOKBOOK", title: "Pix Payment Agent", description: "The smallest thing that works: create a Pix charge, render the QR, send it over WhatsApp. About 50 lines.", href: "/docs/cookbooks/pix-payment-agent" },
  { label: "COOKBOOK", title: "Projects, Keys and Environments", description: "Which project a key acts in, why the project row and not the prefix decides the environment, and how to tell an empty read from a wrong key.", href: "/docs/cookbooks/projects-and-keys" },
  { label: "COOKBOOK", title: "Sandbox to First Live Charge", description: "Run the whole flow against a funded test wallet, then see exactly what changes when you swap the key.", href: "/docs/cookbooks/sandbox-to-live" },
]} />

## Your agent spends

The agent is the buyer. It moves money out of a wallet it governs, inside an allowance someone signed.

<NextStepsGrid items={[
  { label: "COOKBOOK", title: "Shopping Agent", description: "The full buy-side loop: search a real store, open the checkout session, poll to the payable Pix, settle it from the governed wallet.", href: "/docs/cookbooks/shopping-agent" },
  { label: "COOKBOOK", title: "Agent with a Wallet", description: "Create a wallet, bind a funding source, fund it via sandbox Pix, execute a mandate-gated payment, watch the audit trail render.", href: "/docs/cookbooks/agent-with-wallet" },
  { label: "COOKBOOK", title: "What an Allowance Spent", description: "Read what the agent spent under a mandate, and tell an attempt apart from money that actually moved.", href: "/docs/cookbooks/consumer-spend-ledger" },
  { label: "COOKBOOK", title: "Card Bound to a Mandate", description: "Issue a card pinned to the allowance a consumer signed, and the one call that separates an issued card from a governed one.", href: "/docs/cookbooks/issue-card-on-mandate" },
]} />

## Your agent collects

The agent is the merchant. It issues what someone else pays, then invoices and ships against it.

<NextStepsGrid items={[
  { label: "COOKBOOK", title: "E-Commerce Checkout", description: "Discovery, payment, invoice and shipping in one conversation.", href: "/docs/cookbooks/ecommerce-checkout" },
  { label: "COOKBOOK", title: "Marketplace Payout", description: "Split one transaction into platform fee and seller payout: one agent, two settled transactions, one audit trail.", href: "/docs/cookbooks/marketplace-payout" },
  { label: "COOKBOOK", title: "Crypto Pay Agent", description: "Mint a stablecoin payment URL, share it with the buyer, watch for settlement by webhook or by polling.", href: "/docs/cookbooks/crypto-pay-agent" },
  { label: "COOKBOOK", title: "KYC Onboarding", description: "From zero to a provisioned consumer account: open the application, poll it, and read what exists after approval.", href: "/docs/cookbooks/kyc-onboarding" },
]} />

## Govern what it may do

The recipes that put a bound on an agent before it spends, and let you prove afterwards what it did.

<NextStepsGrid items={[
  { label: "COOKBOOK", title: "Hold a Spend for Approval", description: "An approval-required rule that stops a spend before dispatch: poll the hold as the caller, decide it as an operator.", href: "/docs/cookbooks/approval-guardrail" },
  { label: "COOKBOOK", title: "Verify the Audit Chain", description: "Anchor, verify and export the trail: what each verdict means, and which refusals a retry will never fix.", href: "/docs/cookbooks/audit-chain-verify" },
  { label: "COOKBOOK", title: "Open Finance Consent", description: "From the consent at the bank to the ingested statement: initiate, finalise, refresh, revoke.", href: "/docs/cookbooks/open-finance-consent" },
]} />

## Run it in production

Patterns for operating agents, whichever side yours is on.

<NextStepsGrid items={[
  { label: "COOKBOOK", title: "Webhook Listener", description: "React to settled events with a deterministic loop: no agent, no LLM, no surprise. Issue the NF-e, create the label, send the message.", href: "/docs/cookbooks/webhook-listener" },
  { label: "COOKBOOK", title: "Multi-Tenant SaaS", description: "One agent per customer with their own providers and credentials: isolated by design, metered per tenant.", href: "/docs/cookbooks/multi-tenant" },
  { label: "COOKBOOK", title: "Streaming Chat Agent", description: "Stream an agent turn to a browser: sendStream() behind a Next.js route handler, six event types re-emitted as SSE.", href: "/docs/cookbooks/streaming-chat-agent" },
  { label: "COOKBOOK", title: "Find a Capability by Intent", description: "Turn a sentence into a tool name. Three searches answer it over three corpora, and only one costs a single call.", href: "/docs/cookbooks/discover-capability" },
  { label: "COOKBOOK", title: "Webhook Providers Reference", description: "Per-provider inbound signature schemes: HMAC-SHA256, ECDSA P-256, HTTP Basic, shared secret.", href: "/docs/cookbooks/webhook-providers" },
]} />

<Callout type="info">
For output that never touches an upstream, declare per-session fixtures with `cs.create({ mocks: {...} })`. [Test Mode](/docs/concepts/test-mode) has the strict-mode contract and the envelope reference.
</Callout>

## Next steps

<NextStepsGrid items={[
  { label: "QUICKSTART", title: "5-minute quickstart", description: "Before the cookbooks: install the SDK and get a session running.", href: "/docs/quickstart" },
  { label: "CONCEPT", title: "Sessions", description: "The primitive every cookbook builds on.", href: "/docs/concepts/sessions" },
  { label: "CONCEPT", title: "Triggers", description: "Signed HTTP callbacks on settled events, for the webhook recipes.", href: "/docs/concepts/triggers" },
  { label: "REFERENCE", title: "SDK reference", description: "Every method, type and signature the cookbooks use.", href: "/docs/api/sdk" },
]} />
