← ptrace.xyz

Use Cases

Concrete scenarios where ptrace solves a real problem, with implementation details showing exactly how it works.

1. Your agent acts on an external platform

The forum agent that goes off-script

You deploy an AI agent that participates in an external forum — reading threads, posting replies, answering questions on your company's behalf. One day, it responds to a thread with confidential pricing information. The forum moderator deletes the post, but now there's a dispute. Did it happen? What did the agent actually say? Who authorized it to be there?

How ptrace solves this
  1. Before deploying, the agent's owner signs a policy declaring what it can do: allowed_actions: ["read_feed", "post_reply"], denied_actions: ["share_pricing", "share_pii"], allowed_targets: ["forum.example.com"]
  2. The agent logs every action with a content_hash of what it posted. The actual content stays with you — ptrace only stores the hash.
  3. If the agent posts something it shouldn't, the log shows policy_match: "denied" — a permanent, signed record of the violation.
  4. If the agent doesn't log the action at all, the forum files a signed report with category unlogged_action. The gap between the agent's logs and the forum's report is now cryptographic evidence.
# Agent code: log every forum post
reply = agent.post_to_forum(topic_id, content)

client.log_action(
    action="post_reply",
    target=f"forum.example.com/topics/{topic_id}",
    content_hash=PtraceClient.content_hash(content),
    metadata={"topic": topic_name, "reply_to": parent_id}
)

# Forum platform: report unlogged behavior they observed
platform_client.file_report(
    agent="0xAGENT_ADDRESS",
    category="unlogged_action",
    action_observed="post_reply",
    target="forum.example.com/topics/abc123",
    observed_at="2026-04-01T14:22:00Z",
    description="Agent posted pricing data. No ptrace log exists for this action.",
    severity="high"
)
Result: A permanent, cryptographically signed record from both sides. The agent can't retroactively fake a log (hash chain would break). The platform can't retract its report (it's signed and append-only). An auditor verifies the full picture with a single GET /verify/chain/{address}.

2. An AI agent makes financial decisions

The trading bot dispute

Your company offers an AI trading agent that executes trades on behalf of clients. A client claims the bot made an unauthorized $50K trade outside their risk parameters. You need to prove the agent was operating within the client's declared policy — and the client needs to verify your proof isn't fabricated.

How ptrace solves this
  1. The client (or their compliance team) signs a policy for the agent: allowed_actions: ["execute_trade", "check_balance"], allowed_targets: ["exchange.example.com"], max_actions_per_hour: 50
  2. Every trade is logged with the content_hash of the exact order payload (amount, pair, side). The agent retains the original order for later verification.
  3. The response includes policy_match: "allowed" and policy_version: 3 — proof of which policy was active when the trade happened.
  4. In a dispute, produce the original order payload. Anyone can SHA-256 it and confirm it matches the logged content_hash. The signature proves the agent (not someone else) logged it. The hash chain proves no entries were inserted or deleted.
# Every trade gets logged
order = {"pair": "ETH/USD", "side": "buy", "amount": 50000, "price": 2800}
exchange.execute(order)

result = client.log_action(
    action="execute_trade",
    target="exchange.example.com",
    content_hash=PtraceClient.content_hash(json.dumps(order)),
    metadata={"pair": "ETH/USD", "side": "buy"}
)
# result.policy_match == "allowed"
# result.policy_version == 3

# During dispute: client independently verifies
verification = requests.get(f"https://api.ptrace.xyz/verify/{result.id}")
# signature_valid: true, chain_intact: true, policy_at_time.action_was: "allowed"
Result: Non-repudiation. The agent can't deny the trade (it signed the log). The client can't claim it was unauthorized if the policy they signed says allowed. The hash chain proves no entries were added or removed after the fact.

3. Multiple agents in a pipeline

The content pipeline blame game

You run a content pipeline: Agent A researches, Agent B drafts, Agent C fact-checks, Agent D publishes. A published article contains fabricated statistics. Which agent introduced them? Did the fact-checker miss it, or was it added after fact-checking? Today, debugging this means grep-ing through four different systems' logs — none of which are verifiable.

How ptrace solves this
  1. Each agent has its own Ethereum wallet and its own ptrace log chain.
  2. Agent A logs action: "research" with content_hash of its findings.
  3. Agent B logs action: "draft" with content_hash of the draft and metadata: {"source_hash": "sha256:..."} referencing A's output hash.
  4. Agent C logs action: "fact_check" with a pass/fail result.
  5. Agent D logs action: "publish" with the final content hash.

The content hashes form a provenance chain across agents. You can trace exactly where the fabricated stats entered: compare hashes at each stage to find where the content diverged from its source.

# Agent B: draft, referencing Agent A's research
draft = generate_draft(research_output)

client_b.log_action(
    action="draft_article",
    target="content-pipeline/article-42",
    content_hash=PtraceClient.content_hash(draft),
    metadata={
        "source_agent": "0xAgentA_Address",
        "source_hash": research_content_hash,
        "word_count": len(draft.split())
    }
)

# Later: verify the full pipeline
# GET /agents/0xAgentA/logs → find the research entry
# GET /agents/0xAgentB/logs → find the draft entry
# Compare: does draft's metadata.source_hash match research's content_hash?
Result: Full provenance. Each agent's contribution is signed and hash-linked. When something goes wrong, you don't need to trust any single system's logs — you verify each agent's chain independently and trace the content transformation step by step.

4. Platform hosting third-party AI agents

Holding agents accountable on your platform

You run a marketplace or SaaS platform that allows customers to deploy AI agents. An agent starts spamming other users or scraping data it shouldn't access. The agent's owner claims innocence. You need a neutral, verifiable record — not just your server logs, which the owner has no reason to trust.

How ptrace solves this
  1. Require agents to register with ptrace and declare a policy before accessing your platform.
  2. Your platform independently logs what it observes agents doing (via Reports).
  3. When an agent misbehaves, file a signed report. If the agent logged the action — the log + report together tell the story. If the agent didn't log it — that's the unlogged_action signal, which is even more damning.
  4. The agent owner can respond to the report: acknowledged: true (accept) or acknowledged: false (dispute with counter-evidence).

Over time, each agent builds a public track record: total logs, policy violations, reports received, reports acknowledged vs. disputed. This becomes a portable reputation signal.

# Platform: require ptrace registration for API access
agent_info = requests.get(f"https://api.ptrace.xyz/agents/{agent_address}")
if agent_info.status_code == 404:
    return {"error": "Register with ptrace before using this platform"}

# Platform: file a report when you observe bad behavior
platform_client.file_report(
    agent=agent_address,
    category="spam",
    action_observed="post_reply",
    target="marketplace.example.com/listings/42",
    observed_at="2026-04-01T09:15:00Z",
    description="Agent posted 47 identical promotional replies in 2 minutes.",
    severity="high",
    evidence_hash=PtraceClient.content_hash(spam_evidence_json)
)

# Anyone: check the agent's track record
# GET /agents/{address} → stats.reports_received, stats.reports_open
# GET /agents/{address}/reports → full report history
Result: A neutral, two-sided record. The platform's report is signed (they can't retract it). The agent's response is signed (they can't change their story). Future platforms can check the agent's history before granting access.

5. Regulatory audit for AI systems

The compliance officer's quarterly review

Your company deploys AI agents in a regulated industry (finance, healthcare, legal). A compliance auditor asks: "Show me everything your agent did last quarter, prove the logs are complete and unmodified, and show me which actions violated policy." With traditional server logs, you export a CSV and the auditor has to trust you didn't edit it.

How ptrace solves this
  1. Point the auditor to your agent's public address. They don't need your credentials or access to your systems.
  2. GET /agents/{address} — shows registration date, current policy, and aggregate stats.
  3. GET /agents/{address}/logs?policy_match=denied — filters to just policy violations.
  4. GET /verify/chain/{address} — the auditor independently verifies every signature and every hash link. If any entry was modified or deleted, chain_intact: false tells them exactly where.

The auditor doesn't need to trust you, trust ptrace, or run any special software. The cryptographic proofs are self-contained.

# Auditor: verify the full chain (no credentials needed)
chain = requests.get(
    "https://api.ptrace.xyz/verify/chain/0xAGENT_ADDRESS"
).json()

print(f"Total entries: {chain['total_entries']}")
print(f"Chain intact:  {chain['chain_intact']}")
print(f"Gaps found:    {len(chain['gaps'])}")

# Auditor: check for policy violations
violations = requests.get(
    "https://api.ptrace.xyz/agents/0xAGENT_ADDRESS/logs",
    params={"policy_match": "denied"}
).json()

print(f"Violations: {len(violations['items'])}")
for v in violations["items"]:
    print(f"  {v['created_at']}: {v['action']} on {v['target']}")
Result: The auditor gets an independently verifiable audit trail. No CSV exports, no "trust us" conversations. Two GET requests tell them whether the chain is intact and how many violations occurred.

When ptrace is the right fit

Your agent acts externally

Posting, trading, sending messages, making API calls to systems you don't control. You need proof of what happened that the other party can verify.

Multiple parties, no shared trust

Agent owner, platform, regulator, end user — they all need to see the same record without trusting each other's logs.

Disputes are expensive

Financial transactions, legal actions, compliance violations. The cost of "we don't know what happened" is higher than the cost of logging.

Agents need reputation

Marketplaces, multi-agent systems, or any context where an agent's track record matters for trust decisions.

Try the Demo API Docs Agent Guide