TrustLoop Technical Reference

Quick Start

The fastest path is the drop-in proxy — change one environment variable and every OpenAI or Anthropic call is governed automatically.

Option A — OpenAI proxy (no code change)

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-openai-key",
    base_url="https://api.trustloop.live/v1",        # ← only change needed
    default_headers={"x-api-key": "tl_your_key"}     # ← add TrustLoop auth
)
# Everything else is identical to normal OpenAI usage

Option B — Python SDK (explicit intercept)

pip install trustloop-sdk

from trustloop import TrustLoop

tl = TrustLoop(api_key="tl_your_key", agent_name="my-agent")

# Option 1: explicit intercept
result = tl.intercept("send_email", {"to": "user@example.com"})
if result["allowed"]:
    send_email(...)

# Option 2: decorator — wraps a function, blocks it if not allowed
@tl.guard()
def delete_records(table: str, where: dict):
    ...

Authentication

All authenticated endpoints require your TrustLoop API key. Pass it as a header:

x-api-key: tl_your_key_here

Keys are created when you sign up at trustloop.live/signup. Each key belongs to a tenant and carries all associated limits and rules. Retrieve a lost key via POST /api/resend-key with your email.

OpenAI Drop-in Proxy

Endpoint: POST /v1/chat/completions Requires x-api-key

A transparent proxy to the OpenAI Chat Completions API. Set this as your client's base_url. Your OpenAI key goes in the standard Authorization: Bearer header. TrustLoop key goes in x-api-key.

Headers

Python

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-openai-key",
    base_url="https://api.trustloop.live/v1",
    default_headers={
        "x-api-key": "tl_your_key",
        "x-agent-name": "finance-agent"  # optional
    }
)

Node.js

const { OpenAI } = require('openai')

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: 'https://api.trustloop.live/v1',
  defaultHeaders: {
    'x-api-key': process.env.TRUSTLOOP_API_KEY,
    'x-agent-name': 'my-agent'
  }
})

Anthropic Drop-in Proxy

Endpoint: POST /proxy/anthropic/v1/messages Requires x-api-key

Transparent proxy to the Anthropic Messages API. Intercepts tool_use content blocks before returning the response to your agent. Same governance pipeline as the OpenAI proxy.

Headers

Python

import anthropic

client = anthropic.Anthropic(
    api_key="sk-ant-your-key",
    base_url="https://api.trustloop.live/proxy/anthropic",
    default_headers={
        "x-api-key": "tl_your_key",
        "x-agent-name": "my-claude-agent"
    }
)

Python SDK

pip install trustloop-sdk                      # sync (requests)
pip install "trustloop-sdk[async]"             # + async (httpx)
pip install "trustloop-sdk[langchain]"         # + LangChain helpers
pip install "trustloop-sdk[crewai]"            # + CrewAI helpers
pip install "trustloop-sdk[all]"               # everything

Core client

from trustloop import TrustLoop, TrustLoopBlockedError

tl = TrustLoop(api_key="tl_xxx", agent_name="my-agent")

# Explicit intercept
result = tl.intercept("send_email", {"to": "...", "subject": "..."})
if result["allowed"]:
    send_email(...)

# Guard decorator — raises TrustLoopBlockedError if blocked
@tl.guard("delete_records")
def delete_records(table: str, where: dict):
    ...

# LangChain integration
from trustloop.integrations.langchain import wrap_tools
governed_tools = wrap_tools(tl, tools)

# CrewAI integration
from trustloop.integrations.crewai import governed_tool

@governed_tool(tl)
class SendEmailTool(BaseTool):
    ...

Node.js SDK

npm install trustloop

const { TrustLoop } = require('trustloop')

const tl = new TrustLoop({ apiKey: process.env.TRUSTLOOP_API_KEY, agentName: 'my-agent' })

const result = await tl.intercept('send_email', { to: 'user@example.com' })
if (result.allowed) {
  await sendEmail(...)
}

MCP — Claude Desktop

Connect Claude Desktop by adding TrustLoop as an MCP server in your config. Every tool call Claude makes passes through TrustLoop's governance pipeline.

{
  "mcpServers": {
    "trustloop": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.trustloop.live/sse?api_key=tl_xxx"]
    }
  }
}

REST Intercept

Use the REST endpoint when you want explicit control — call it before any sensitive action in your own code, no SDK needed.

POST /api/intercept POST Auth

Evaluates a tool call against your governance rules. Call this before executing any sensitive action.

Request body

Response

{ "allowed": true, "decision": "ALLOWED" }

{ "allowed": false, "decision": "BLOCKED", "message": "Blocked by governance rule: ..." }

{ "allowed": false, "decision": "ESCALATED", "status": "pending_approval", "approval_id": "uuid" }

GET /api/logs GET Auth

Returns the last 100 tool call records for your account, newest first.

Query params

GET /api/stats GET Auth

Returns aggregate counts for the current month plus per-agent breakdown.

{
  "total": 1842,
  "allowed": 1790,
  "blocked": 48,
  "pending": 4,
  "usage": { "plan": "growth", "used": 1842, "limit": 1000000 },
  "agents": {
    "used": 3, "limit": 10,
    "breakdown": [
      { "name": "finance-agent", "total": 920, "allowed": 898, "blocked": 22 }
    ]
  }
}

Approval Rules Auth

Kill-Switch Auth

Pending Approvals Auth

Governance Pipeline

Every call to /api/intercept or through the proxy runs this pipeline in order. The first rule that matches stops evaluation and returns a decision.

AI Rule Caching

To avoid hitting the Anthropic API on every tool call, TrustLoop uses two in-memory caches:

• Rules cache — fetched rules per tenant, TTL 60 seconds. Invalidated immediately on rule create/delete.
• Decision cache — AI decision keyed by tenantId:toolName:argsHash, TTL 5 minutes. Invalidated when rules change. In practice this achieves ~90%+ cache hit rate for agents with consistent calling patterns.

PII & Compliance

Before any tool call is written to the audit log, TrustLoop's compliance middleware automatically:

• Masks PII — emails, phone numbers, card numbers, names, national IDs replaced with [PII MASKED]
• Redacts secrets — API keys, passwords, tokens, bearer credentials replaced with [REDACTED]
• Scores risk — each tool call assigned LOW / MEDIUM / HIGH risk based on tool name and argument patterns

Additional compliance endpoints:

• GET /api/compliance/stats — PII masked count, secrets redacted count, risk breakdown
• GET /api/compliance/dsar — Full GDPR Art. 15 / CCPA data subject access request export (JSON)
• DELETE /api/logs/purge?days=N — Delete logs older than N days (data retention)

Blockchain Anchoring

Every hour, TrustLoop hashes all tool call logs from the previous hour and records the hash on the Polygon Mainnet via a smart contract at 0xd2544fc3164ac0eBfb6B7A2c193800F9651Fc46F.

This creates an independently verifiable tamper-evident record. If any logs are deleted or modified in Supabase, recomputing the hash from the remaining records will not match what's on-chain.

Anchor records are stored in the blockchain_anchors table: { log_hash, tx_hash, log_count, created_at }. Anyone can verify a hash by querying Polygon directly (polygonscan.com).

Plan Limits

Limits are enforced at the intercept point. When a limit is exceeded, the API returns HTTP 429 with a clear error message. Usage resets on the 1st of each calendar month.