Finault Documentation

60-Second Quickstart

Get Finault up and running in three simple steps. Wrap your existing AI client and start generating verifiable economic receipts for every call.

Step 1: Install

Install the Finault SDK for your language:

pip install finault

npm install @finault/sdk

Step 2: Wrap

Wrap your existing OpenAI or Anthropic client in two lines:

from finault import finault
client = finault.wrap(client)

import { wrap } from '@finault/sdk';
const client = wrap(openaiClient);

Step 3: Done

Every AI call is now sealed with a verifiable economic receipt.

Each request to your wrapped client automatically generates a unique, tamper-proof seal that records the cost, parameters, and outcome. You can verify the integrity of any seal anytime.

SDK Reference

Complete API reference for the Finault SDK. All functions are available in Python and Node.js.

wrap(client)

Wraps an existing OpenAI or Anthropic client to automatically seal every AI call.

Signature

def wrap(client: OpenAI | Anthropic) -> WrappedClient

wrap(client: OpenAI | Anthropic): WrappedClient

Parameters

Parameter	Type	Description
client	OpenAI \| Anthropic	Your existing OpenAI or Anthropic client instance

Returns

WrappedClient — A proxy client that intercepts all API calls and seals them

Example

from openai import OpenAI
from finault import finault

client = OpenAI(api_key="sk-...")
wrapped = finault.wrap(client)

response = wrapped.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}]
)

seal_id = response.finault_seal_id  # Extract seal ID

import OpenAI from 'openai';
import { wrap } from '@finault/sdk';

const client = new OpenAI({ apiKey: 'sk-...' });
const wrapped = wrap(client);

const response = await wrapped.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Hello' }]
});

const sealId = response.finault_seal_id;  // Extract seal ID

finault.seal(data)

Manually seal arbitrary data with a tamper-proof cryptographic seal.

Signature

def seal(data: dict | str) -> Seal

seal(data: object | string): Seal

Parameters

Parameter	Type	Description
data	dict \| str	Any data structure or string to seal

Returns

Seal — Object with id, timestamp, and hash

Example

from finault import finault

data = {
    "user_id": "user_123",
    "action": "purchase",
    "amount": 99.99
}

seal = finault.seal(data)
print(seal.id)        # "seal_abc123..."
print(seal.timestamp) # "2026-03-22T14:30:00Z"

import { seal } from '@finault/sdk';

const data = {
    user_id: 'user_123',
    action: 'purchase',
    amount: 99.99
};

const result = seal(data);
console.log(result.id);        // "seal_abc123..."
console.log(result.timestamp); // "2026-03-22T14:30:00Z"

finault.verify(seal_id)

Verify the integrity and authenticity of a seal.

Signature

async def verify(seal_id: str) -> VerifyResult

async verify(seal_id: string): Promise<VerifyResult>

Parameters

Parameter	Type	Description
seal_id	str	The seal ID to verify

Returns

VerifyResult — {valid: bool, data: dict, hash: str, timestamp: str}

Example

result = await finault.verify("seal_abc123...")

if result.valid:
    print("Seal is authentic")
    print(f"Data: {result.data}")
else:
    print("Seal has been tampered with")

const result = await finault.verify('seal_abc123...');

if (result.valid) {
    console.log('Seal is authentic');
    console.log(`Data: ${JSON.stringify(result.data)}`);
} else {
    console.log('Seal has been tampered with');
}

finault.cost(seal_id)

Get the cost breakdown for a sealed AI call.

Signature

async def cost(seal_id: str) -> CostBreakdown

async cost(seal_id: string): Promise<CostBreakdown>

Parameters

Parameter	Type	Description
seal_id	str	The seal ID to get cost for

Returns

CostBreakdown — {total: float, input_tokens: float, output_tokens: float, model: str}

Example

breakdown = await finault.cost("seal_abc123...")

print(f"Total: ${breakdown.total:.4f}")
print(f"Input tokens: {breakdown.input_tokens}")
print(f"Output tokens: {breakdown.output_tokens}")
print(f"Model: {breakdown.model}")

const breakdown = await finault.cost('seal_abc123...');

console.log(`Total: $${breakdown.total.toFixed(4)}`);
console.log(`Input tokens: ${breakdown.input_tokens}`);
console.log(`Output tokens: ${breakdown.output_tokens}`);
console.log(`Model: ${breakdown.model}`);

Gateway Headers

Use custom headers to pass metadata and control behavior through the Finault Gateway. The gateway is available at gw.finault.ai/v1.

Custom Headers

Header	Description	Example
X-Finault-Customer	Identify the end customer or user. Useful for multi-tenant applications.	`customer_id_12345`
X-Finault-Agent	Tag the agent or system making the request.	`my_bot_v2.1`
X-Finault-Tag	Add arbitrary metadata tags for classification and filtering.	`priority:high,dept:support`
X-Finault-Budget	Set a per-request cost budget in cents. Request fails if estimated cost exceeds budget.	`500` (5 USD limit)

Example: Setting Custom Headers

import requests

url = "https://gw.finault.ai/v1/chat/completions"

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "X-Finault-Customer": "customer_789",
    "X-Finault-Agent": "support_bot",
    "X-Finault-Tag": "support,urgent",
    "X-Finault-Budget": "1000"  # 10 USD limit
}

payload = {
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello"}]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

const axios = require('axios');

const url = 'https://gw.finault.ai/v1/chat/completions';

const headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'X-Finault-Customer': 'customer_789',
    'X-Finault-Agent': 'support_bot',
    'X-Finault-Tag': 'support,urgent',
    'X-Finault-Budget': '1000'  // 10 USD limit
};

const payload = {
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Hello' }]
};

axios.post(url, payload, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));

API Reference

RESTful API for interacting with Finault seals, verifying integrity, and accessing cost data.

Endpoints

Method	Path	Description
GET	/v1/seals	List all seals for your account (paginated)
GET	/v1/seals/:id	Get details of a specific seal
GET	/v1/chain/:id	Get the audit chain for a seal (all modifications and verifications)
GET	/v1/costs	Get cost aggregates and breakdowns (daily, weekly, monthly)
POST	/v1/verify	Verify one or more seals in batch

GET /v1/seals

Retrieve a paginated list of all seals associated with your account.

Example Request

curl

curl -X GET "https://api.finault.ai/v1/seals?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /v1/seals/:id

Get the complete details of a specific seal, including data, timestamp, and verification status.

Example Request

curl

curl -X GET "https://api.finault.ai/v1/seals/seal_abc123xyz" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /v1/chain/:id

Get the complete audit chain for a seal. Shows all verifications, modifications, and timestamp proofs.

Example Request

curl

curl -X GET "https://api.finault.ai/v1/chain/seal_abc123xyz" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /v1/costs

Get aggregated cost data across all seals, with breakdowns by model, time period, and customer.

Example Request

curl

curl -X GET "https://api.finault.ai/v1/costs?period=daily&start_date=2026-03-15" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /v1/verify

Batch verify one or more seals for integrity in a single request.

Example Request

curl

curl -X POST "https://api.finault.ai/v1/verify" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "seal_ids": [
      "seal_abc123xyz",
      "seal_def456uvw"
    ]
  }'

Troubleshooting

Common issues and their solutions.

Seal not appearing in responses

Cause: The SDK wrapper may not be properly initialized, or the API key is invalid.

Fix: Verify that you are calling finault.wrap() on your client object and that your Finault API key is set correctly in the environment. Check that you are accessing response.finault_seal_id after the call completes.

Cost shows $0

Cause: Cost data may not be available immediately if the call just completed, or the model is not recognized by Finault's pricing database.

Fix: Wait 30 seconds and retry the cost lookup. If the issue persists, ensure your model is in Finault's supported models list. You can also call the /v1/costs endpoint to see all available data.

Gateway timeout

Cause: The gateway is experiencing high load, or your request is timing out before the upstream API responds.

Fix: Implement exponential backoff in your client. Set the X-Finault-Budget header to prevent overly complex requests. Check the status page for ongoing incidents.

Attribution missing from cost breakdown

Cause: The X-Finault-Customer or X-Finault-Agent header was not provided with the request.

Fix: Include the custom headers when making requests through the gateway. This improves cost tracking and attribution. See Gateway Headers for details.

MCP Server

Finault provides an MCP (Model Context Protocol) server for seamless integration with Claude and other AI systems. The MCP server exposes Finault functionality as a set of tools that AI assistants can call directly.

Available Tools

The Finault MCP server exposes the following tools:

seal_data — Seal arbitrary data with a tamper-proof signature
verify_seal — Verify the integrity of a previously sealed record
get_cost_breakdown — Retrieve cost details for a sealed AI call
list_seals — List all seals matching filters (customer, agent, date range)
get_audit_chain — Get the complete audit chain for a seal
batch_verify — Verify multiple seals in a single batch operation

Configuration

To connect the Finault MCP server to your system, use the following configuration:

JSON

{
  "mcpServers": {
    "finault": {
      "command": "finault-mcp-server",
      "args": ["--api-key", "fk_live_YOUR_API_KEY"],
      "env": {
        "FINAULT_GATEWAY": "gw.finault.ai",
        "FINAULT_LOG_LEVEL": "info"
      }
    }
  }
}

Example Conversation

Here's an example of how an AI assistant might use the Finault MCP tools:

User Request

User: "I need to verify that the AI call we made yesterday
was legitimate and get the cost breakdown."

Assistant Response

Assistant: I'll help you verify that call and get the cost details.
Let me search for seals from yesterday...

[Calling: list_seals with filters for yesterday's date]

Found seal "seal_xyz789abc" from your call.
Now let me verify its integrity and get the cost breakdown...

[Calling: verify_seal with seal_id="seal_xyz789abc"]
[Calling: get_cost_breakdown with seal_id="seal_xyz789abc"]

Great! Here are the results:

Verification: ✓ Valid (seal has not been tampered with)
Created: 2026-03-21 14:35:22 UTC

Cost Breakdown:
  Model: gpt-4
  Input tokens: 1,240
  Output tokens: 856
  Total cost: $0.0482

The seal confirms that this was a legitimate, unmodified AI call
with the exact cost shown above.