v4.3

Documentation

Finault is the economic proof layer for AI infrastructure. Connect your AI providers, get sealed receipts for every call, and see per-customer profitability in real time.

Quick Start

Connect your first AI provider in 3 lines of code. Finault works as a drop-in proxy — change your base URL and every call gets sealed automatically.

Example
from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.finault.ai/v1",
    api_key="your-openai-key",  # NOT your Finault key
    default_headers={
        "X-Finault-Key": "fnlt_sk_...",       # Your Finault API key
        "X-Finault-Customer-Id": "cust_001",  # Optional: per-customer tracking
        "X-Finault-Revenue": "0.15",          # Optional: triggers margin calc
    }
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}]
)
# That's it. Every call is now sealed with cost + margin.

Sealed Receipts

Every AI call produces a cryptographically sealed receipt (AIEI). Each receipt contains WHO made the call, WHAT was called, how much it COST, and the policy RULES applied. Receipts are SHA-256 hashed and appended to an RFC 6962 Merkle tree.

Example
// Verify a seal
GET /v1/verify/{seal_id}

// Get Merkle inclusion proof
GET /v1/proofs/inclusion?seal_id={seal_id}

// Get signed tree head
GET /v1/proofs/tree-head

Per-Customer Margins

See real-time profitability for every customer. Finault matches AI costs to revenue (from Stripe or manual ingestion) and computes margins per customer, per agent, per transaction.

Example
// Dashboard summary
GET /v1/dashboard/summary

// Per-customer margin breakdown
GET /v1/analytics/margins

// Margin forensics — why did margin change?
GET /v1/margins/forensics/analyze

Close Pack Chain

Monthly sealed audit packages. Each Close Pack contains all costs, margins, journal entries, and a SHA-256 chain hash linking to the previous month. Tamper-proof, auditor-ready, verifiable forever.

Example
// Generate monthly close pack
POST /v1/closepack/generate

// Get latest close pack
GET /v1/closepack/latest

// Validate close pack schema
POST /v1/closepack/validate

Intelligence Engine

Automated detection of cache opportunities, model routing optimizations, and cost anomalies. The engine runs continuously and surfaces actionable savings recommendations.

Example
// Cache opportunity detection
GET /v1/intelligence/cache-analysis

// Routing recommendations
GET /v1/intelligence/routing

// Cost anomaly detection
GET /v1/intelligence/anomalies

// Unified intelligence report
GET /v1/intelligence/report

Compliance Reports

Generate compliance documentation for EU AI Act (Article 12), Colorado SB-205, and SOC 2. Reports pull from your sealed data — every claim is backed by cryptographic proof.

Example
// EU AI Act Article 12 compliance report
GET /v1/compliance/article12/{close_pack_id}

// Colorado SB-205 compliance report
GET /v1/compliance/colorado-sb205/{close_pack_id}

// GL Journal export (QuickBooks/Xero compatible)
GET /v1/export/gl-journal?format=csv

Merkle Proof Verification

Generate O(log N) inclusion proofs for any seal within its Close Pack. Verify any individual seal against the Merkle root without downloading the entire chain. Any party can independently verify by hashing up the tree.

Example
// Generate Merkle inclusion proof
POST /v1/seal/merkle-proof
{
  "seal_hash": "a1b2c3d4e5f6...",
  "close_pack_id": "cp_2026_03"
}

// Response includes proof array with
// sibling hashes and direction (left/right)
// at each level of the Merkle tree

Selective Disclosure

Prove specific facts about your AI economics without revealing raw numbers. Companies can demonstrate margin ranges for the Finault Index without exposing absolute revenue or costs. Uses salted field-level Merkle trees to prevent dictionary attacks.

Example
// Generate selective disclosure proof
POST /v1/seal/selective-proof
{
  "fields": {
    "org_id": "org_acme",
    "margin_pct": 64.8,
    "seal_count": 1247000
  },
  "reveal": ["margin_pct", "seal_count"]
}
// Unrevealed fields stay hidden

Dark Debt Scanner

Scan AI-generated text for patterns that create hidden liabilities. Returns a Dark Debt Score (0-100) with categorized risks: financial commitments, legal language, PII exposure, confidentiality leaks, hallucination indicators, and output length anomalies.

Example
// Scan AI output for risk patterns
POST /v1/dark-debt/scan-output
{
  "output": "I guarantee a $5,000 refund...",
  "context": {
    "agent_id": "support-bot-v3",
    "customer_id": "cust_acme"
  }
}
// Returns: dark_debt_score, risks[]

W3C Verifiable Credentials

Export any Finault seal as a W3C Verifiable Credential and verify it with standard VC tooling. Ed25519Signature2020 proof type. Portable, interoperable, standards-compliant.

Example
// Verify a seal exported as a W3C VC
POST /v1/seal/verify-credential
{
  "credential": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://finault.ai/credentials/v1"
    ],
    "type": ["VerifiableCredential", "FinaultSeal"],
    "issuer": "did:key:z6Mk..."
  }
}

Named Chains (SPEC-PROOF-V2)

One seal, many audit trails. Each customer, product, environment, and compliance framework gets its own independently verifiable chain. Auditors verify a specific scope without seeing other business data. Chain-scoped Close Packs for granular reporting.

Example
// List all chains for your org
GET /v1/chains

// Verify a specific chain's integrity
GET /v1/chains/{chain_id}/verify

// Export chain data
GET /v1/chains/{chain_id}/export

// Consistency proof between chains
GET /v1/chains/{chain_id}/consistency

// Chain-scoped Close Pack
POST /v1/chains/{chain_id}/close-pack

Margin-Aware Model Routing

When revenue is configured, the gateway can route requests to the model that maximizes margin while meeting a quality threshold. Filters out unprofitable models, respects quality tiers, and logs the routing decision in the seal metadata.

Example
// Enable via org settings or per-request
// X-Finault-Revenue: 0.15  (revenue header)
// X-Finault-Customer-Id: cust_acme

// The routing engine:
// 1. Calculates cost for each model
// 2. Filters unprofitable options
// 3. Applies quality threshold
// 4. Selects highest-margin model

API Reference

MethodEndpointDescription
GET/v1/healthGateway health + DB status
GET/v1/pricingModel pricing table
POST/v1/seal/verifyVerify seal integrity
GET/.well-known/finault-verification-keyHMAC verification key
POST/v1/chat/completionsProxy AI call (OpenAI-compatible)
POST/v1/completionsCompletions proxy + seal
POST/v1/embeddingsEmbeddings proxy + seal
GET/v1/chainsNEWList all Named Chains
GET/v1/chains/{id}/verifyNEWVerify chain integrity
GET/v1/chains/{id}/exportNEWExport chain data
GET/v1/chains/{id}/consistencyNEWConsistency proof
POST/v1/chains/{id}/close-packNEWChain-scoped Close Pack
POST/v1/seal/ingestSeal from SDK callback data
POST/v1/ingest/focusFOCUS 1.3 cost data
GET/v1/export/focusExport in FOCUS format
POST/v1/ingest/langfuseLangfuse traces
POST/v1/ingest/otelOpenTelemetry spans
GET/v1/agents/didAgent DID:key identity
POST/v1/ucan/delegateNEWCreate UCAN delegation
POST/v1/ucan/validateNEWValidate UCAN token
GET/v1/scoreNEWFinault Score (5 dimensions)
GET/v1/reportNEWMonthly intelligence report
GET/v1/compliance/article12NEWEU AI Act Article 12 report
POST/v1/dark-debt/scan-outputNEWScan output for risk patterns
GET/v1/margins/summaryNEWOrg-wide margin summary (by customer, provider, model)
GET/v1/margins/{id}NEWSingle customer margin detail
GET/v1/margins/{id}/trendNEWMargin trend over time (day/week/hour)
GET/v1/chains/{id}/summaryNEWChain aggregate economics
POST/v1/compliance/exportNEWCompliance evidence export (EU AI Act, SB-205, NIST)
GET/v1/demo/sealSample seal (public, no auth)
POST/v1/auth/signupCreate account (returns API key)
POST/v1/auth/loginSign in (returns JWT)
GET/v1/auth/meCurrent user + organization
GET/v1/margin/thresholdsMargin alert configuration
POST/v1/margin/thresholdsConfigure margin alerts
POST/v1/integrations/lagoConfigure Lago billing

MCP Server

Query your AI economics from Claude Desktop or any MCP-compatible client.

View MCP tools

Base URL

https://gateway.finault.ai/v1

AI proxy endpoints require your provider key (OpenAI, Anthropic, etc.) as the api_key and your Finault key in the X-Finault-Key header. Management endpoints require a Bearer token from login. Get your API key (fnlt_sk_...) from the dashboard after signing up.