SDKs

Python, TypeScript, CLI, and Go SDKs

Attesto exposes four first-class developer surfaces: Python, TypeScript, Go, and the Attesto CLI. They share the same Proofstream protocol, golden vectors, verifier matrix, production origin, and secret-handling rules.

Article 13 support and Article 12 evidence with one integration line

For high-risk AI systems, Article 12 is about technical logging capability and traceability, while Article 13 is about transparency and information that helps deployers and users understand the system. In Attesto terms, the exact one-line integration is export OPENAI_BASE_URL=http://localhost:8765/v1: it points OpenAI-compatible calls at the Attesto Gateway so automatic evidence capture can start. The deterministic attesto report article12 output explains what was recorded and independently verifiable, and teams can use that verified trail as support material for Article 13 documentation. This is evidence support, not a legal conformity statement.

The concrete one-line gateway integration that makes this true is:

export OPENAI_BASE_URL=http://localhost:8765/v1

In production, replace localhost with the deployed gateway host and keep both the provider key and Attesto system key in server-side secret storage.

Use this pattern when you own a Python function boundary. The decorator records commitments over arguments, return value, timing, source reference, and failures; the report summarizes coverage without using an LLM.

from attesto import AttestoV2Client, attest, article12
import os

with AttestoV2Client(api_key=os.environ["ATTESTO_API_KEY"]) as capture:
    @attest(capture, stream_id="str_...")
    def score_case(case: dict) -> dict:
        return {"decision": "manual_review", "policy_id": "policy-2026-01"}

    score_case({"case_id": "case-2026-0001"})
with AttestoV2Client.with_bearer_token(os.environ["ATTESTO_TENANT_TOKEN"]) as operator:
    print(article12(operator, "str_..."))

The capture path uses a system API key; the report path reads tenant stream events and therefore requires a tenant/operator bearer token.

attesto --token-env ATTESTO_TENANT_TOKEN \
  report article12 --stream str_... --output report.md

What the SDK handles

The SDKs are intentionally thin server-side clients. They do not hide the evidence model, but they remove repetitive transport work so your application can focus on choosing the right event shape and verifying the returned evidence.

Capability matrix

Python

pip install attesto

import os
from datetime import UTC, datetime
from attesto import AttestoClient

attesto = AttestoClient(api_key=os.environ["ATTESTO_API_KEY"])
ack = attesto.log_event(
    type="inference",
    status="verified",
    ts=datetime.now(UTC),
    payload={
        "model": "risk-service-v4",
        "score": 0.91,
        "policy_id": "policy-2026-01",
    },
)
print(ack.id)

Python async

import os
from datetime import UTC, datetime
from attesto import AsyncAttestoClient

async with AsyncAttestoClient(api_key=os.environ["ATTESTO_API_KEY"]) as attesto:
    ack = await attesto.log_event(
        type="ai.decision",
        status="verified",
        ts=datetime.now(UTC),
        payload={"decision": "manual_review", "score": 91},
    )
    print(ack.id)

TypeScript

npm install @attesto/sdk

import { AttestoClient } from "@attesto/sdk";

const attesto = new AttestoClient({
  apiKey: process.env.ATTESTO_API_KEY!,
});

const ack = await attesto.logEvent({
  type: "inference",
  status: "verified",
  ts: new Date(),
  payload: {
    model: "risk-service-v4",
    score: 0.91,
    policy_id: "policy-2026-01",
  },
});
console.log(ack.id);

TypeScript attestedFetch

Use attestedFetch when an OpenAI-compatible SDK or framework accepts a custom fetch implementation. It records commitments only, never raw prompts or completions. strict: true fails closed when evidence cannot be submitted; fail-open mode must be monitored.

import { AttestoV2Client, attestedFetch } from "@attesto/sdk";

const client = new AttestoV2Client({ apiKey: process.env.ATTESTO_API_KEY! });
const fetchWithEvidence = attestedFetch(client, {
  streamId: "str_...",
  capture: "commitments",
  strict: true,
});

Proofstream v2 client

Use AttestoV2Client when you need stream-level receipts, checkpoint consistency, witness policy visibility, verifier bundles, and offline verification helpers.

from attesto import AttestoV2Client
from datetime import UTC, datetime
import os

with AttestoV2Client(api_key=os.environ["ATTESTO_API_KEY"]) as attesto:
    stream = attesto.create_stream(
        use_case="ai-decision-history",
        policy_id="policy-2026-01",
    )
    receipt = attesto.log_event(
        stream_id=stream.stream_id,
        source_ref="source-event-001",
        event_type="decision",
        occurred_at=datetime.now(UTC),
        payload={"decision": "review", "score": 91},
    )
    stored = attesto.get_receipt(receipt.stream_event_id)
    report = attesto.verify_receipt(
        receipt=stored.receipt,
        public_key_hex=os.environ["ATTESTO_RECEIPT_SIGNER_PUBLIC_KEY_HEX"],
        stream_event_id=receipt.stream_event_id,
    )
    assert report.ok

TypeScript Proofstream:

import { AttestoV2Client } from "@attesto/sdk";

const attesto = new AttestoV2Client({
  apiKey: process.env.ATTESTO_API_KEY!,
});

const stream = await attesto.createStream({
  useCase: "ai-decision-history",
  policyId: "policy-2026-01",
});

const receipt = await attesto.logEvent(stream.streamId, {
  sourceRef: "case-2026-0001:decision-1",
  eventType: "ai.decision",
  occurredAt: new Date(),
  payload: { decision: "manual_review", score: 91 },
});

const report = await attesto.verifyReceipt({
  receipt: receipt.receipt,
  streamEventId: receipt.streamEventId,
  publicKeyHex: process.env.ATTESTO_RECEIPT_SIGNER_PUBLIC_KEY_HEX!,
});
if (!report.ok) throw new Error(report.problems.join("; "));

Go

Use Go for infrastructure automation, security tooling, cloud workers, and verifier services. The Go SDK currently uses only the Go standard library and is resolved from the public go.attesto.eu/sdk module path.

go get go.attesto.eu/sdk

package main

import (
  "context"
  "fmt"
  "log"
  "os"

  attesto "go.attesto.eu/sdk"
)

func main() {
  client, err := attesto.NewClient(os.Getenv("ATTESTO_API_KEY"))
  if err != nil {
    log.Fatal(err)
  }

  stream, err := client.CreateStream(context.Background(), attesto.StreamCreateInput{
    UseCase: "ai-decision-history",
    PolicyID: "policy-2026-01",
  })
  if err != nil {
    log.Fatal(err)
  }

  receipt, err := client.LogEvent(context.Background(), stream.StreamID, attesto.EventInput{
    SourceRef: "case-2026-0001:decision-1",
    EventType: "ai.decision",
    Payload: attesto.M{"decision": "manual_review", "score": 91},
  })
  if err != nil {
    log.Fatal(err)
  }

  fmt.Println(receipt.StreamEventID, receipt.EventHash)
}

CLI

The Attesto CLI is the operator and verifier surface for scripted workflows. It supports JSON output, local config, stream/event actions, receipt verification, bundle verification, fork evidence, quorum evidence, connectors, Local Vault, and release-readiness evidence checks. It never prints stored API keys, tenant tokens, or connector secrets.

CLI command reference

cd sdk/go
go run ./cmd/attesto --json version

go run ./cmd/attesto --json \
  --api-key-env ATTESTO_API_KEY \
  streams create \
  --use-case ai-decision-history \
  --policy-id policy-2026-01

Offline receipt verification:

go run ./cmd/attesto --json receipts verify \
  --file receipt.json \
  --public-key-hex "$ATTESTO_RECEIPT_SIGNER_PUBLIC_KEY_HEX"

Production readiness evidence check:

go run ./cmd/attesto --json readiness lifecycle
go run ./cmd/attesto --json readiness fork-defense
go run ./cmd/attesto --json readiness production

Marketplace publisher automation:

go run ./cmd/attesto --json marketplace init \
  --output attesto.connector.json \
  --slug signed-webhook-evidence \
  --name "Generic Signed Webhook Evidence" \
  --version 1.0.0 \
  --category compliance \
  --summary "Produces Attesto evidence for signed webhook events." \
  --description "Produces verifiable Proofstream events for signed webhook payloads." \
  --publisher-slug attesto \
  --publisher-name Attesto \
  --repository-url https://git.rotz.ai/rotzmediagroup/attesto-v1/src/branch/attesto-2.0/connectors/webhook \
  --docs-url https://docs.attesto.eu/manuals/connectors.html#signed \
  --provider-url https://docs.attesto.eu/manuals/connectors.html#signed \
  --auth-mode signed-webhook \
  --auth-scopes webhook:read \
  --sync-modes webhook \
  --event-types webhook.event.received \
  --canary-ref release/attesto-2.0-connector-assurance-readiness/result.json \
  --capabilities proofstream,offline-verification

go run ./cmd/attesto --json marketplace validate \
  --manifest-file attesto.connector.json

go run ./cmd/attesto --json \
  --token-env ATTESTO_TENANT_TOKEN \
  marketplace submit \
  --manifest-file attesto.connector.json \
  --source-ref https://git.rotz.ai/rotzmediagroup/attesto-v1/src/branch/attesto-2.0/connectors/webhook \
  --visibility public \
  --pricing-model free

Operator endpoints

Tenant/operator endpoints require bearer-token mode. Use this only in trusted operator automation and never in public clients.

from attesto import AttestoV2Client

operator = AttestoV2Client.with_bearer_token(
    os.environ["ATTESTO_TENANT_TOKEN"],
)
streams = operator.list_tenant_streams()
forks = operator.list_fork_evidence(streams[0]["streamId"])

const operator = new AttestoV2Client({
  apiKey: process.env.ATTESTO_TENANT_TOKEN!,
  authMode: "bearer",
});

const streams = await operator.listTenantStreams();
const forks = await operator.listForkEvidence(String(streams[0].streamId));

operator, err := attesto.NewBearerClient(os.Getenv("ATTESTO_TENANT_TOKEN"))
if err != nil { log.Fatal(err) }
streams, err := operator.ListTenantStreams(context.Background(), "", 100, 0)
if err != nil { log.Fatal(err) }

Offline and online verify helpers

SDK verification methods are useful in services that receive Attesto receipts or bundles and need to fail closed before accepting them.

from attesto import AttestoV2Client
from datetime import UTC, datetime
import os

with AttestoV2Client(api_key=os.environ["ATTESTO_API_KEY"]) as attesto:
    report = attesto.verify_object(
        kind="bundle",
        proof_object=bundle_object,
    )
    if not report.ok:
        raise RuntimeError(report.problems)

const report = await attesto.verifyObject({
  kind: "bundle",
  object: bundleObject,
});

if (!report.ok) {
  throw new Error(report.problems.join("; "));
}

MockAttesto for local tests

attesto.testing.MockAttesto is a Python test harness for local CI and integration tests. It uses the same canonical hashing and receipt shapes as the SDK, but signs with a per-instance throwaway mock key and marks objects as mock evidence. Use it to test your application flow without network access or an Attesto account; do not use mock receipts in production evidence or customer bundles.

MockAttesto is intentionally fail-closed against real trust roots: verification with a production witness key must reject mock evidence. That keeps tests fast without creating a path for synthetic evidence to pass as production proof.

Companion packages and edge surfaces

The core SDKs stay small. Separate packages cover edge relay, MCP tooling, workflow nodes, and the future independent witness node. These packages must never become hidden transitive dependencies of the core SDKs.

pip install attesto-mcp
pipx install attesto-local-vault
npm install n8n-nodes-attesto

Specified as a privacy-preserving observation node package. Current customer-operated witness behavior is available through Local Vault witness mode; standalone attesto-witness, @attesto/witness, and go.attesto.eu/witness should be installed only after release evidence marks that package green.

Security rules

• Use SDKs from server-side code only.
• Store system keys in your secret manager and inject them at runtime.
• Do not place system keys in frontend bundles, mobile apps, query strings, or logs.
• Use the default production origin unless your tenant has a private deployment origin.
• Keep idempotency enabled for every write path.