Money

Five methods that call a meta-tool with a typed argument and hand back a typed result instead of a ToolResult to cast. Each one is execute("codespar_<tool>", args) on the wire, so what a page under Meta-tools says about the tool's actions and providers applies here unchanged; what these pages add is the TypeScript shape and what the wrapper throws.

All five share one failure rule: when the tool result is not success, the wrapper throws a plain Error whose message is <method> failed: <error>. Network failures and timeouts surface as they do on execute.

charge

Creates something the buyer pays: a Pix QR, a boleto, a hosted card checkout or a wallet redirect. Distinct from codespar_pay, which is an outbound transfer and has no typed wrapper. amount is in major units.

const charge = await session.charge({
  amount: 150,
  currency: "BRL",
  method: "pix",
  description: "Order 0000",
  buyer: { name: "Example Buyer", email: "buyer@example.com" },
});
console.log(charge.id, charge.status, charge.pix_copy_paste);

interface ChargeResult {
  id: string;
  status: string;
  amount: number;
  currency: string;
  method: string;
  /** Hosted payment URL when the provider issues one */
  charge_url?: string;
  pix_qr_code?: string;
  pix_copy_paste?: string;
  raw?: unknown;
}

Throws Error("charge failed: ...") when the tool result is not success; otherwise as execute.

Related codespar_charge. Settlement is asynchronous: correlate it with paymentStatus using the tool_call_id that execute returns for the same call.

ship

Quote carriers, buy a label, or track a shipment, over one address-and-items envelope. Routes BR domestic shipments through Melhor Envio (Correios and private carriers); the router picks the cheapest carrier unless service_level says otherwise.

const quote = await session.ship({
  action: "quote",
  origin: { postal_code: "01310100" },
  destination: { postal_code: "20040020" },
  items: [{ weight_g: 500, width_cm: 20, height_cm: 10, length_cm: 30 }],
});
console.log(quote.carrier, quote.cost_minor, quote.estimated_delivery);

interface ShipResult {
  id: string;
  status: string;
  tracking_code?: string;
  label_url?: string;
  carrier?: string;
  estimated_delivery?: string;
  /** Minor units */
  cost_minor?: number;
  raw?: unknown;
}

Throws Error("ship failed: ...") when the tool result is not success; otherwise as execute.

Related codespar_ship.

ledger

The books, not the money: post a double-entry journal entry, read an account's balances, create an account, or read an agentic receipt, on the tenant's self-hosted Lerian Midaz ledger. Source debits must equal destination credits in the same asset. Amounts are in minor units.

const entry = await session.ledger({
  action: "entry",
  asset: "BRL",
  scale: 2,
  source: [{ account: "@wallet/user_0000", amount: 15000 }],
  destination: [{ account: "@revenue/store", amount: 15000 }],
  description: "Order 0000 settled",
});
console.log(entry.id, entry.status);

interface LedgerResult {
  /** Transaction or account id (entry / account) */
  id?: string | null;
  status?: string;
  account_id?: string | null;
  alias?: string | null;
  /** Per-asset available + on-hold amounts (balance) */
  balances?: unknown;
  raw?: unknown;
}

// action=receipt and action=receipts return these instead:
interface LedgerReceiptResult { found: boolean; receipt?: AgenticReceipt; receipt_id?: string }
interface LedgerReceiptsResult { receipts: AgenticReceipt[]; count: number }

The return type is LedgerResult for every action; for receipt and receipts the value on the wire has the LedgerReceiptResult and LedgerReceiptsResult shapes, which @codespar/types exports for the cast.

Throws Error("ledger failed: ...") when the tool result is not success; otherwise as execute.

Related codespar_ledger, Audit chain for what an agentic receipt proves.

issue

Issue a virtual or physical card, freeze, unfreeze or cancel one, or read its status, on the tenant's card-issuing program. Creates spend instruments; it does not move money by itself.

const card = await session.issue({
  action: "card-virtual",
  cardholder_id: "chd_0000",
  program_id: "prg_0000",
});
console.log(card.id, card.last_four, card.status);

interface IssueResult {
  id?: string | null;
  status?: string | null;
  card_type?: string | null;
  last_four?: string | null;
  cardholder_id?: string | null;
  program_id?: string | null;
  raw?: unknown;
}

Throws Error("issue failed: ...") when the tool result is not success; otherwise as execute.

Related codespar_issue.

shop

Buy-side shopping: search a store's live catalog, start a checkout, poll it to a payable Pix. The argument and result are discriminated on action, so the result type follows the action without a cast. Checkout is asynchronous: checkout returns in_progress at once; poll checkout_status until ready_for_payment (which carries pix_copia_e_cola and total_minor) or canceled (which carries error). Requires a runtime with a registered codespar_shop implementation; a self-hosted runtime without one answers Tool not registered.

const found = await session.shop({ action: "search", query: "dog food", merchant: "cobasi" });
if ("products" in found) {
  const sku = found.products[0]?.variants[0]?.sku_id;
  console.log(sku);
}

const started = await session.shop({
  action: "checkout",
  merchant: "cobasi",
  items: [{ variant_id: "sku_0000", quantity: 1 }],
});
if ("checkout_session_id" in started) {
  const status = await session.shop({
    action: "checkout_status",
    checkout_session_id: started.checkout_session_id,
  });
  if ("pix_copia_e_cola" in status) console.log(status.pix_copia_e_cola);
}

interface ShopOffer {
  product_id: string;
  /** Offer-level SKU when there is a single buyable SKU */
  sku_id?: string;
  title?: string;
  /** Minor units */
  price_minor?: number;
  currency?: string;
  image?: string;
  url?: string;
  available: boolean;
  variants: ShopVariant[];
}

interface ShopVariant {
  /** Pass this as the checkout item's variant_id; the product id is not buyable */
  sku_id: string;
  title?: string;
  price_minor?: number;
  currency?: string;
  available: boolean;
}

Throws Error("shop failed: ...") when the tool result is not success, including Tool not registered; otherwise as execute. A canceled checkout is a value with error set, not a throw.

Related codespar_shop for the rails, the cancel reasons and the state machine; settle the Pix with codespar_pay through execute.