SDK bridge

Python quickstart

Submit a signed decision + outcome pair with public summaries. Flow: Get an API key → Copy code → Run. Examples below always work with placeholders; we pre-fill when you’re signed in.

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

Placeholders use YOUR_API_KEY and YOUR_ORGANIZATION_ID. Sign up to get real values on the dashboard (and 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

Easiest path — no SDK install · org YOUR_ORGANIZATION_ID · 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

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
BASE_URL = "https://audifact.io"
ORGANIZATION_ID = "YOUR_ORGANIZATION_ID"


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"{BASE_URL}/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 (any automated system: bot, workflow, model, etc.)
requests.post(
    f"{BASE_URL}/agents",
    json={
        "organization_id": ORGANIZATION_ID,
        "name": "my-agent",
        "public_key": public_key_b64,
    },
    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, {
    "organization_id": ORGANIZATION_ID,
    "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, {
    "organization_id": ORGANIZATION_ID,
    "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: {BASE_URL}/e/{decision['event_hash']}")
print("Outcome:", outcome)
print(f"Outcome proof: {BASE_URL}/e/{outcome['event_hash']}")

AudifactClient v0.3.1

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

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

Simple mode (below) — pass api_key only; org resolves at init, default-agent auto-registers on first log_decision. Explicit mode (commented) pins org YOUR_ORGANIZATION_ID and optionally names your agent.

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

Install v0.3.1

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

Usage — ~12 lines, no manual org or agent setup

#!/usr/bin/env python3
"""Audifact SDK v0.4.0 - copy, paste, submit."""
# pip install "git+https://github.com/audifact/audifact-sdk.git@v0.4.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
BASE_URL = "https://audifact.io"

keys = AudifactClient.generate_keypair()
client = AudifactClient(private_key_b64=keys["private_key"], base_url=BASE_URL, api_key=API_KEY)
# v0.4.0: org resolves 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: {BASE_URL}/e/{decision['event_hash']}")
print(f"Outcome proof: {BASE_URL}/e/{outcome['event_hash']}")

# Explicit mode (multiple orgs / extra safety):
# ORGANIZATION_ID = "YOUR_ORGANIZATION_ID"
# client = AudifactClient(
#     private_key_b64=keys["private_key"],
#     base_url=BASE_URL,
#     api_key=API_KEY,
#     default_organization_id=ORGANIZATION_ID,
# )
# client.ensure_agent("my-agent")

Terminal one-liner

Paste into bash — installs deps and submits decision + outcome.

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
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, BASE_URL, ORG = "af_...", "https://audifact.io", "YOUR_ORGANIZATION_ID"  # API_KEY: use the secret shown only at creation
sk = SigningKey.generate()
pk = base64.b64encode(sk.verify_key.encode()).decode()

def post(p):
    body = json.dumps(p, sort_keys=True, separators=(",", ":")).encode()
    sig = base64.b64encode(sk.sign(body).signature).decode()
    r = requests.post(f"{BASE_URL}/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()

requests.post(f"{BASE_URL}/agents", json={"organization_id": ORG, "name": "my-agent", "public_key": pk}, timeout=10).raise_for_status()
ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
decision_fields = {
    "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",
    "metadata_json": {"decision_reason": "oversold bounce", "confidence": 0.82, "regime": "trend"},
    "ts": ts,
}
d = post({"organization_id": ORG, "agent_public_key": pk, "event_type": "decision", "context_json": {"rsi": 28, "price": 64250, "vol": 1840, "market_regime": "trend"}, **decision_fields})
o = post({"organization_id": ORG, "agent_public_key": pk, "event_type": "outcome", "decision_event_hash": d["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"{BASE_URL}/e/{d['event_hash']}")
print("Outcome proof:", f"{BASE_URL}/e/{o['event_hash']}")
PY

What these examples do

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

Register an agent identity (bot, workflow, model, etc.) under your organization
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