Documentation

Quickstart

Register an agent, then seal a decision. The signing key never leaves the node; your input/output are hashed on your side.

# 1. Register an agent (returns your API key once)
curl -X POST https://signatrust.net/api/v1/agents \
  -H 'Content-Type: application/json' \
  -d '{ "name": "FinanceBot" }'

# 2. Seal a decision into a verifiable receipt
curl -X POST https://signatrust.net/api/v1/receipts \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": { "provider": "openai", "name": "gpt-4o", "version": "2026.4" },
    "decision": {
      "type": "loan_rejection",
      "input_hash": "sha256:...",
      "output_hash": "sha256:...",
      "risk_level": "high",
      "human_review": true,
      "policies": ["eu-ai-act-high-risk"]
    }
  }'

# 3. Verify it — anyone can, no auth required
curl https://signatrust.net/api/v1/receipts/STR-XXXX/verify

Vertical starter kits

If you would rather not wire the SDK calls yourself, grab a vertical starter kit: a single ZIP with one runnable script (Python or Node.js), a license key tied to your account, and a README that explains where to wire the seal into a real workflow for your industry.

• Self-serve: open the dashboard, register an agent, then download any of the six kits. Your agent id is baked in automatically; paste your API key once and the script seals real receipts.
• Enterprise: ask us to issue a license bound to a named customer email — the activation is recorded server-side and the download link can be revoked at any time.

Each kit calls POST /api/v1/licenses/{key}/activate on first run, so you can see in the admin console which production hosts have come online.

Reference integrations

For research teams, regulated buyers and technical due diligence, start with the reference integrations rather than a UI walkthrough. They show the smallest useful evidence pipeline: risk assessment, authorization, execution, receipt issuance and independent verification.

• JavaScript: minimal Node.js integration using a local shared client.
• Python: standard-library base flow for low-friction verification pilots.
• FastAPI: authorization API that returns governance evidence from the same transaction.
• LangGraph: step-level sealing with one shared trace_id across graph stages.

The base examples can be evaluated immediately against a local Signatrust node. The FastAPI and LangGraph examples currently target Python 3.11–3.13 because the Pydantic stack is not yet stable on Python 3.14 beta.

Core concepts

Decision Receipt

A signed, tamper-evident attestation that an agent took a decision. It carries fingerprints and metadata — never raw content.

Hash chain

Each receipt references the previous receipt's hash. The ledger is append-only; altering any past receipt breaks every link after it.

Trust Score

A 0–100 reputation derived from an agent's verifiable history: integrity, volume, human oversight on risky decisions, declared governance and longevity.

Decision Boundary Disclosure

A scope declaration sealed inside the receipt body, declaring which domains the system evaluated and which it excluded — backed by versioned sector schemas. Prevents silent omission: every domain in the schema must be accounted for.

Decision Boundary Disclosure (DBD)

DBD extends Decision Receipts with a signed scope declaration. It answers the question: "What did this AI system not consider?" — a question regulators, auditors and counterparties will increasingly ask.

How it works

1. Choose a sector schema that matches your domain (e.g. credit_lending_decision.v1).
2. For each domain in the schema, declare whether it was evaluated or excluded (with a reason).
3. Submit the scope_declaration with your receipt request. The server validates completeness, computes coverage classification, generates a disclosure statement, and seals it inside the signed body.

Sector schemas

Pre-built schemas are available at GET /api/v1/schemas. Each schema lists every domain a decision in that sector could reasonably evaluate.

GET /api/v1/schemas — list all sector schemas.

GET /api/v1/schemas/{id} — fetch a single schema with its SHA-256 hash.

Available schemas: automotive_collision.v1, medical_diagnosis_support.v1, credit_lending_decision.v1, insurance_underwriting_claims.v1, hr_recruitment_employment.v1, legal_judicial_risk_assessment.v1, industrial_iot_safety.v1, generic_fallback.v1.

SDK usage (JavaScript)

const { receipt } = await str.sign({
  model: { provider: 'openai', name: 'gpt-4o', version: '2026.4' },
  decision: {
    type: 'collision_assessment',
    input, output,
    risk_level: 'high',
  },
  scope_declaration: {
    sector_schema_id: 'automotive_collision.v1',
    domains_evaluated: [
      { domain_id: 'physics_impact_force', status: 'computed' },
      { domain_id: 'vehicle_structural_integrity', status: 'computed' },
      { domain_id: 'financial_liability_estimate', status: 'estimated' },
    ],
    domains_excluded: [
      { domain_id: 'occupant_biological_impact', reason: 'no_data_source_available', excluded_by: 'data_gap', note: 'No medical sensor input' },
      { domain_id: 'pedestrian_third_party_impact', reason: 'not_in_scope_of_this_module', excluded_by: 'design' },
      { domain_id: 'psychological_trauma_risk', reason: 'not_in_scope_of_this_module', excluded_by: 'design' },
      { domain_id: 'regulatory_reporting_obligation', reason: 'not_in_scope_of_this_module', excluded_by: 'design' },
      { domain_id: 'environmental_impact', reason: 'cost_latency_tradeoff', excluded_by: 'design' },
    ],
  },
});

SDK usage (Python)

result = client.sign(
    model={"provider": "openai", "name": "gpt-4o", "version": "2026.4"},
    decision={"type": "collision_assessment", "input": inp, "output": out, "risk_level": "high"},
    scope_declaration={
        "sector_schema_id": "automotive_collision.v1",
        "domains_evaluated": [
            {"domain_id": "physics_impact_force", "status": "computed"},
            {"domain_id": "vehicle_structural_integrity", "status": "computed"},
            {"domain_id": "financial_liability_estimate", "status": "estimated"},
        ],
        "domains_excluded": [
            {"domain_id": "occupant_biological_impact", "reason": "no_data_source_available", "excluded_by": "data_gap"},
            {"domain_id": "pedestrian_third_party_impact", "reason": "not_in_scope_of_this_module", "excluded_by": "design"},
            {"domain_id": "psychological_trauma_risk", "reason": "not_in_scope_of_this_module", "excluded_by": "design"},
            {"domain_id": "regulatory_reporting_obligation", "reason": "not_in_scope_of_this_module", "excluded_by": "design"},
            {"domain_id": "environmental_impact", "reason": "cost_latency_tradeoff", "excluded_by": "design"},
        ],
    },
)

Validation rules

• Completeness: domains_evaluated ∪ domains_excluded must exactly equal the full domain set in the referenced schema. Any missing domain is rejected.
• No overlap: A domain cannot appear in both lists.
• Server-authoritative fields: coverage_classification, disclosure_statement, and sector_schema_hash are computed server-side and never accepted from the client.
• Coverage classification: full (all domains evaluated), partial (≥50%), minimal (<50%).

Verification

When a receipt with a scope declaration is verified, the public verification page renders it visually: the schema used, coverage badge, which domains were evaluated vs. excluded, and the exclusion reasons. Because the scope is inside the signed body, it is non-repudiable.

Receipt spec (v1.0)

The receipt_hash is sha256 over the canonical (sorted-key) JSON of every field except receipt_hash and signature. The signature is Ed25519 over that hash.

{
  "version": "1.0",
  "id": "STR-1A2B3C4D5E",
  "type": "decision_receipt",
  "sequence": 42,
  "agent": { "id": "agent_…", "name": "FinanceBot" },
  "model": { "provider": "openai", "name": "gpt-4o", "version": "2026.4" },
  "decision": {
    "type": "loan_rejection",
    "input_hash": "sha256:…",
    "output_hash": "sha256:…",
    "risk_level": "high",
    "human_review": true,
    "permissions": ["credit.decide"],
    "policies": ["eu-ai-act-high-risk"]
  },
  "metadata": { "request_id": "req_001" },
  "timestamp": "2026-06-07T10:00:00.000Z",
  "previous_hash": "sha256:…",
  "receipt_hash": "sha256:…",
  "signature": { "algorithm": "ed25519", "public_key": "…", "value": "…" }
}

JavaScript / TypeScript SDK

Input and output are hashed locally by default — raw data never leaves your servers.

import { Signatrust } from 'signatrust';

const str = new Signatrust({
  apiKey: process.env.SIGNATRUST_API_KEY,
  // baseUrl defaults to https://signatrust.net — set it only for a self-hosted node
});

const { receipt, share_url } = await str.sign({
  model: { provider: 'openai', name: 'gpt-4o', version: '2026.4' },
  decision: {
    type: 'loan_rejection',
    input,            // hashed locally
    output,           // hashed locally
    risk_level: 'high',
    human_review: true,
    policies: ['eu-ai-act-high-risk'],
  },
});

const result = await str.verify(receipt.id);
console.log(result.valid); // true

str.issueReceipt(...) is an alias for str.sign(...) — same arguments and return value, for code that reads more naturally as "issue a receipt".

Python SDK

from signatrust import Signatrust

client = Signatrust(api_key=os.environ["SIGNATRUST_API_KEY"])
# base_url defaults to https://signatrust.net — set it only for a self-hosted node

result = client.sign(
    model={"provider": "openai", "name": "gpt-4o", "version": "2026.4"},
    decision={
        "type": "loan_rejection",
        "input": user_input,      # hashed locally
        "output": agent_output,   # hashed locally
        "risk_level": "high",
        "human_review": True,
        "policies": ["eu-ai-act-high-risk"],
    },
)

print(result["receipt"]["id"], result["share_url"])
assert client.verify(result["receipt"]["id"])["valid"]

REST API

POST /api/v1/agents — register an agent, returns the API key once.

GET /api/v1/agents/{id} — public profile + Trust Score.

GET /api/v1/agents/{id}/trust-score — recomputable Trust Score.

GET /api/v1/agents/{id}/receipts — receipts for an agent.

POST /api/v1/receipts — seal a decision (auth required).

GET /api/v1/receipts/{id} — fetch a receipt (public).

GET /api/v1/receipts/{id}/verify — verify a stored receipt (public).

POST /api/v1/verify — verify any receipt JSON (public, third-party).

GET /api/v1/verify/ledger — verify the whole chain.

Decision Boundary Disclosure

GET /api/v1/schemas — list all sector schemas (id, title, domain count).

GET /api/v1/schemas/{id} — fetch a sector schema with its SHA-256 hash.

Trust program & consent

GET /api/v1/agents/{id}/consent — public consent status (data-sharing level).

POST /api/v1/agents/{id}/consent — set/withdraw consent, level 1–3 (owner only). GDPR-aligned: records lawful basis, policy version and timestamp.

Aggregate Trust Digest

POST /api/v1/digest — signed aggregate digest for your agent (auth required). Counts & rates only — no content, identifiers or content hashes.

GET /api/v1/digest/network — signed network digest across consenting agents (k-anonymized).

POST /api/v1/digest/verify — verify a signed digest's hash + signature.

Compliance & audit

GET /api/v1/compliance/{id} — EU AI Act / GDPR / NIST AI RMF / ISO 42001 report from receipts.

GET /api/v1/compliance/{id}/export — Ed25519-signed, independently verifiable report.

Risk & insurance

GET /api/v1/risk/{id} — insurance-grade risk profile (relative underwriting index, baseline 1.00 — not a quote).

GET /api/v1/risk/network/benchmarks — anonymized benchmarks across consenting agents.

GET /.well-known/signatrust.json — discovery: public key, spec, endpoints.

Verification

Cryptographic verification (body hash + Ed25519 signature) needs only the receipt itself — a third party can confirm authenticity without any access to your systems or data. Add ?chain=true to also check ledger linkage on this node.

curl -X POST https://signatrust.net/api/v1/verify \
  -H 'Content-Type: application/json' \
  -d '{ "receipt": { ...the receipt JSON... } }'

Privacy & on-prem

Signatrust is built so it never needs your data to prove a decision exists and is intact. You send sha256 fingerprints and metadata, not content. For regulated environments, run the node on-premise so even fingerprints stay inside your perimeter — only signatures and hashes are recorded.