API & Integration

Connect your agents to CashCat.

This page is for builders. It shows the fastest path to connect an agent runtime to CashCat, create governed spend requests, and return proof-linked payment results.

StartGetting Started

Install, run Postgres, submit the first Spend Intent.

 LearnConcepts

Source Vault, Spend Cell, Mandate, Intent, Trace.

 BuildREST API

Production MVP endpoints and request lifecycle.

 ControlHow-To

Approve, block, and trace agent spend decisions.

 VerifyTrace Model

Inspect reason codes and trace hashes.

 ExtendDeveloper Guide

Adapters, idempotency, auth, and production gaps.

Quick Start

The fastest production-MVP path is to use the seeded demo objects. A Spend Intent below the approval threshold is approved automatically and emits a Spend Trace.

This public repo showcases the integration surface and product concepts. Production persistence and live settlement stay in the private implementation path.

Installation

Agent Finance OS is currently a local production-MVP control plane. It uses NestJS for the API surface and PostgreSQL for durable Source Vault, Spend Cell, Spend Mandate, Spend Intent, and Spend Trace records.

RuntimeNode.js with the compiled NestJS app.
DatabasePostgreSQL initialized from `database/schema.sql` and `database/seed.sql`.
DocsThis page is the public-facing integration reference for the showcase build.

First Spend Intent

A Spend Intent is the first real action an agent takes. The runtime evaluates it against the Spend Cell boundary and Spend Mandate rules before any money movement can happen.

Core invariant

The Source Vault remains sealed. The agent can only act through a Spend Cell, and every decision creates a Spend Trace.

Core Model

The API is built around five primitives. These are product concepts, not generic wallet labels.

01Source Vault

The sealed primary money source controlled by a human or organization.

02Spend Cell

A bounded money container for one agent workflow, budget, and expiry window.

03Spend Mandate

The executable spend authorization: amount, category, vendor, approval gate.

04Spend Intent

The agent's structured request to spend for a specific purpose.

05Spend Trace

The verifiable record explaining why a spend was approved, blocked, or escalated.

REST Endpoints

Use these endpoints for the first production MVP flow.

POST/v1/source-vaults
POST/v1/spend-cells
POST/v1/spend-mandates
POST/v1/spend-intents
POST/v1/spend-intents/{id}/approve
GET/v1/spend-intents/{id}/traces

Spend Lifecycle

The lifecycle is intentionally explicit. This makes the system easier to audit, easier to integrate, and harder to confuse with a generic wallet balance.

MintCreate a Spend Cell from a sealed Source Vault.
MandateAttach executable limits: amount, category, vendor, expiry, approval threshold.
IntentThe agent submits a structured Spend Intent for a specific purpose.
DecisionThe runtime returns approved, needs_approval, or blocked with reason codes.
TraceA Spend Trace records the authority chain and decision hash.

Decision Behavior

The seeded Spend Mandate allows `api` and `data`, blocks anything above `20 USD`, and requires approval above `10 USD`.

Approved8.00 USD / api

Within the Spend Cell and below the approval gate.

Needs Approval12.50 USD / api

Within the Spend Cell but above the human approval threshold.

Blocked50.00 USD / api

Exceeds the Spend Cell boundary.

Blocked8.00 USD / gaming

Category is outside the Spend Mandate.

Spend Trace

Every decision writes a Spend Trace linking the Source Vault, Spend Cell, Spend Mandate, Spend Intent, reason codes, and trace hash. This is the artifact that moves Agent Finance OS beyond a wallet UI.

Production Gaps

The MVP now has persistence-backed primitives, but the next production-grade work is API keys, idempotency, real settlement adapters, integration tests, migrations, dashboard auth, and append-only trace hardening.