SDK bridge

Python quickstart

Submit a signed decision + outcome pair with public summaries. Flow: Get an API key → Copy code → Run. Examples use API_BASE for machine traffic (api.audifact.io in production) and SITE_BASE for proof links (audifact.io). We pre-fill when you’re signed in.

Copy the scripts now - add your key when you have one

Placeholder uses YOUR_API_KEY - organization is always taken from the key. Sign up to get a real key on the dashboard (we can pre-fill this page next visit).

1
Get an API key

Sign up → Dashboard → API Keys → copy the af_… secret (shown once).
2
Copy a script

Standalone Python (no SDK install), Full SDK, or terminal one-liner.
3
Run it

Creates decision + outcome with public summaries on the proof page.

Standalone Python

No SDK install · raw REST · API key only · stdlib json

Recommended: Create a venv first: python3 -m venv .venv && source .venv/bin/activate && pip install requests PyNaCl

#!/usr/bin/env python3
"""Audifact quickstart - decision + outcome pair with public summaries."""
# Recommended: Create a venv first: python3 -m venv .venv && source .venv/bin/activate && pip install requests PyNaCl
# Auth is the API key only (X-API-Key). Server scopes agents + events from the key.
# API_BASE = machine traffic (POST /events, /agents). SITE_BASE = proof links (/e/...).

import base64
import json
from datetime import datetime, timezone

import requests
from nacl.signing import SigningKey

API_KEY = "af_..."  # replace with the key shown only once at creation
API_BASE = "https://api.audifact.io"
SITE_BASE = "https://audifact.io"


def submit_event(signing_key, public_key_b64, payload):
    body = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
    signature = base64.b64encode(signing_key.sign(body).signature).decode()
    response = requests.post(
        f"{API_BASE}/events",
        data=body,
        headers={
            "X-API-Key": API_KEY,
            "X-Signature": signature,
            "Content-Type": "application/json",
        },
        timeout=10,
    )
    response.raise_for_status()
    return response.json()


signing_key = SigningKey.generate()
public_key_b64 = base64.b64encode(signing_key.verify_key.encode()).decode()

# Register an agent identity (bot, workflow, model, etc.). Scoped by API key.
requests.post(
    f"{API_BASE}/agents",
    json={
        "name": "my-agent",
        "public_key": public_key_b64,
    },
    headers={"X-API-Key": API_KEY},
    timeout=10,
).raise_for_status()

ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")

decision = submit_event(signing_key, public_key_b64, {
    "agent_public_key": public_key_b64,
    "event_type": "decision",
    "context_json": {"rsi": 28, "price": 64250, "vol": 1840, "market_regime": "trend"},
    "metadata_json": {"decision_reason": "oversold bounce", "confidence": 0.82, "regime": "trend"},
    "decision_type": "trade_signal",
    "decision_value": "btc/long",
    "decision_label": "Enter BTC long - RSI oversold, vol expansion",
    "public_decision_type": "trade_signal",
    "public_decision_value": "btc/long",
    "public_decision_label": "Enter BTC long - RSI oversold",
    "ts": ts,
})

outcome = submit_event(signing_key, public_key_b64, {
    "agent_public_key": public_key_b64,
    "event_type": "outcome",
    "decision_event_hash": decision["event_hash"],
    "outcome_type": "pnl",
    "outcome_value": 1.0,
    "outcome_label": "pnl = +1.0",
    "public_outcome_type": "pnl",
    "public_outcome_value": 1.0,
    "public_outcome_label": "pnl = +1.0",
    "ts": ts,
})

print("Decision:", decision)
print(f"Decision proof: {SITE_BASE}/e/{decision['event_hash']}")
print("Outcome:", outcome)
print(f"Outcome proof: {SITE_BASE}/e/{outcome['event_hash']}")

AudifactClient v0.5.0

from audifact import AudifactClient · org from API key · auto agent · copy-paste and submit

Open-source SDK v0.5.0: https://github.com/audifact/audifact-sdk

Pass api_key only - organization is always taken from the key; default-agent auto-registers on first log_decision. Multi-org: create one API key per organization.

Replace YOUR_API_KEY / af_... with a key from the dashboard after signup.

Install v0.5.0

pip install "git+https://github.com/audifact/audifact-sdk.git@v0.5.0"

Usage - ~12 lines, no org id or agent setup

#!/usr/bin/env python3
"""Audifact SDK v0.5.0 - copy, paste, submit."""
# pip install "git+https://github.com/audifact/audifact-sdk.git@v0.5.0"
# https://github.com/audifact/audifact-sdk

from datetime import datetime, timezone

from audifact import AudifactClient

API_KEY = "af_..."  # replace with the key shown only once at creation
API_BASE = "https://api.audifact.io"   # machine: POST /events, /agents
SITE_BASE = "https://audifact.io"  # humans: proof pages /e/...

keys = AudifactClient.generate_keypair()
client = AudifactClient(
    private_key_b64=keys["private_key"],
    base_url=API_BASE,
    api_key=API_KEY,
)
# v0.5.0: org from API key; agent auto-registers on first submit

ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
decision = client.log_decision(
    context_json={"rsi": 28, "market_regime": "trend"},
    public_decision_label="Enter BTC long - RSI oversold",
    public_decision_type="trade_signal",
    public_decision_value="btc/long",
    public_context_json={
        "timeframe": "4h",
        "indicators": {"rsi": 28, "vol_change_pct": 18},
    },
    ts=ts,
)
outcome = client.log_outcome(
    decision_event_hash=decision["event_hash"],
    outcome_type="pnl",
    outcome_value=1.0,
    public_outcome_label="pnl = +1.0",
    public_outcome_type="pnl",
    public_outcome_value=1.0,
    public_output_json={"result": "win", "pnl": 1.0},
    ts=ts,
)
print(f"Decision proof: {SITE_BASE}/e/{decision['event_hash']}")
print(f"Outcome proof: {SITE_BASE}/e/{outcome['event_hash']}")

Terminal one-liner

Paste into bash - installs deps, registers an agent, submits decision + outcome. Auth is the API key only (no org id in the payload).

Recommended: Create a venv first: python3 -m venv .venv && source .venv/bin/activate && pip install requests PyNaCl

# Recommended: Create a venv first: python3 -m venv .venv && source .venv/bin/activate && pip install requests PyNaCl
# Auth is the API key only - server scopes the request from the key.
# API_BASE = machine; SITE_BASE = proof links.
python3 -m venv .venv && source .venv/bin/activate && pip install requests PyNaCl && python3 <<'PY'
import base64, json, requests
from datetime import datetime, timezone
from nacl.signing import SigningKey

API_KEY = "af_..."  # replace af_... with the secret shown only at key creation
API_BASE = "https://api.audifact.io"
SITE_BASE = "https://audifact.io"

sk = SigningKey.generate()
pk = base64.b64encode(sk.verify_key.encode()).decode()

def post(payload):
    body = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
    sig = base64.b64encode(sk.sign(body).signature).decode()
    r = requests.post(
        f"{API_BASE}/events",
        data=body,
        headers={
            "X-API-Key": API_KEY,
            "X-Signature": sig,
            "Content-Type": "application/json",
        },
        timeout=10,
    )
    r.raise_for_status()
    return r.json()

# Register agent (scoped by X-API-Key)
requests.post(
    f"{API_BASE}/agents",
    json={"name": "my-agent", "public_key": pk},
    headers={"X-API-Key": API_KEY},
    timeout=10,
).raise_for_status()

ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
decision = post({
    "agent_public_key": pk,
    "event_type": "decision",
    "context_json": {"rsi": 28, "price": 64250, "vol": 1840, "market_regime": "trend"},
    "metadata_json": {"decision_reason": "oversold bounce", "confidence": 0.82, "regime": "trend"},
    "decision_type": "trade_signal",
    "decision_value": "btc/long",
    "decision_label": "Enter BTC long - RSI oversold, vol expansion",
    "public_decision_type": "trade_signal",
    "public_decision_value": "btc/long",
    "public_decision_label": "Enter BTC long - RSI oversold",
    "ts": ts,
})
outcome = post({
    "agent_public_key": pk,
    "event_type": "outcome",
    "decision_event_hash": decision["event_hash"],
    "outcome_type": "pnl",
    "outcome_value": 1.0,
    "public_outcome_type": "pnl",
    "public_outcome_value": 1.0,
    "public_outcome_label": "pnl = +1.0",
    "ts": ts,
})
print("Decision proof:", f"{SITE_BASE}/e/{decision['event_hash']}")
print("Outcome proof:", f"{SITE_BASE}/e/{outcome['event_hash']}")
PY

What these examples do

Recommended: Create a venv first: python3 -m venv .venv && source .venv/bin/activate && pip install requests PyNaCl

Authenticate with X-API-Key - organization is set server-side from the key
Register an agent identity (bot, workflow, model, etc.)
Submit a decision with structured decision fields and public summaries
Submit an outcome linked via decision_event_hash
Print proof URLs for both events

MCP (Model Context Protocol)

Agents can call Audifact natively via MCP tools on the same API host. Authenticate with your X-API-Key header.

GET /mcp/tools: Discover tools with JSON Schema inputs (log_decision, log_outcome, get_proof, register_agent, list_my_recent_decisions).
POST /mcp/call: Invoke a tool: {"name": "log_decision", "arguments": {...}}

Tool responses follow MCP format: content, structuredContent, and isError.

Managed Mode (default for MCP): omit signing fields and pass agent_name - Audifact securely manages and signs on behalf of the agent. Private keys are never returned. Events are immutable once recorded.

Client-side signing (maximum provenance): use the SDK pattern - agent_private_key_b64, or agent_public_key + signature.

Decision fields (hash-protected)

Three first-class fields on every event - included in the canonical hash and immutable once recorded:

decision_type: Category for reporting - e.g. trade_action, model_route
decision_value: Machine-readable value - e.g. buy_long, gpt-4
decision_label: Human-readable label (optional) - e.g. Buy BTC long - RSI oversold on 4h chart

public_decision_* is decision-side; set public_outcome_* on outcomes so proof pages never show private fields. metadata_json is for extra rich data (not in the core decision triple). All fields are optional - omit any you don't need.

Framework use cases · Home