---
title: Audit chain
description: An append-only, hash-chained record of every tool call and money movement — exactly-once, tamper-evident, and exportable for compliance.
---

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

# Audit chain

<Callout title="Why it exists" type="info">
Agents move money. The audit chain is the **CFO-grade record** of everything they did — every tool call, every payment, every KYC check — written append-only and hash-chained so it can be proven untampered after the fact.
</Callout>

Every governed action in CodeSpar appends an event to a per-tenant audit chain:

- **Append-only.** Events are never updated or deleted — corrections are new events that reference the original.
- **Hash-chained.** Each event carries a hash over its contents plus the previous event, so any retroactive edit breaks the chain and is detectable.
- **Exactly-once.** An action is attested once and only once, whether it was dispatched through `session.execute()`, the chat-loop `session.send()`, or a raw `proxy_execute`. Client-SDK tool calls are attested with `attested_by: client_sdk`; server-side dispatch with the server attestor.
- **Self-auditing exports.** Even reading the chain out is itself an audited event.

## What gets recorded

Meta-tool calls, raw provider calls, money movement (charge / pay / payout settlement), KYC dispositions, mandate spends, and policy decisions — each with its `tool_call_id`, resolved rail, idempotency key, and outcome.

## API

| Endpoint | Purpose |
|---|---|
| `GET /v1/audit/events` | Browse-only, paginated listing of chain events for the project |
| `GET /v1/orgs/:orgId/audit/…` (export) | Stream a slice of the chain (Postgres cursor) for SIEM / archival. Over the row limit returns `413`; the export itself appends an `audit_export` event |
| `POST /v1/audit/anchors/verify` | Verify chain integrity against the published anchors — confirms no event was altered or removed |

Audit events also drive the **incident lifecycle** — anomalous or policy-flagged events can be opened, triaged, and resolved as incidents.

## See also

- [Guardrails](/docs/concepts/guardrails) — the policy decisions that the chain records
- [Wallets](/docs/concepts/wallets) — programmable spend, every movement attested
- [Async settlement](/docs/concepts/async-settlement) — settlement events land on the chain