Developer Docs

Agent Attestation API & SDK

Everything you need to add runtime compliance attestation to your AI agents. Python SDK, REST API, MCP server, x402 payments, and verification.

Quick Start
Authentication
Attestation Scopes
Event Ingestion
Verification
MCP Server
x402 Payments
Trust Tiers
Error Codes
Links

Quick Start

Get your first attestation in under 60 seconds.

Terminalpip install agentapproved

Pythonfrom agentapproved import AgentApprovedHandler

handler = AgentApprovedHandler(
    agent_id="my-agent",
    api_key="ap_your_key",
    endpoint="https://app.agentapproved.ai",
)

# Attach to any LangChain agent — events captured automatically
agent = create_agent(callbacks=[handler])
agent.invoke({"input": "..."})

# Record human oversight (optional, boosts compliance score)
handler.record_oversight(reviewer_id="jane", decision="approved")

# End session and request attestation
handler.end_session()
handler.shutdown()

Authentication

API keys are created via a public endpoint. No account registration required.

Create a Key

POST https://app.agentapproved.ai/api/v1/keys/create

Rate limited to 3 requests per IP per 24 hours.

Request{
  "label": "my-agent"
}

Response{
  "key": "ap_...",
  "label": "my-agent",
  "created_at": "2026-03-27T12:00:00Z"
}

Keys cannot be retrieved after creation. Save your key immediately. If lost, create a new one.

Using Your Key

Pass your key as a Bearer token in the Authorization header:

HeaderAuthorization: Bearer ap_your_key

Attestation Scopes

Each scope maps your agent's runtime behaviour against a specific compliance framework.

Scope	Framework	Requirements
`eu-ai-act-art12`	EU AI Act Article 12	6 logging requirements
`singapore-mgf`	Singapore AI Governance	8 requirements, 4 dimensions
`agentapproved-basic-v1`	AgentApproved Basic	Identity, logging, human link, track record
`agentapproved-integrity-v1`	Integrity Oath	6 ethical principles
`full`	All frameworks	Composite score, Gold/Silver/Bronze tiers

Request an Attestation

POST /api/v1/attest

cURLcurl -X POST https://app.agentapproved.ai/api/v1/attest \
  -H "Authorization: Bearer ap_your_key" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "my-agent", "scope": "full"}'

Response{
  "agent_id": "my-agent",
  "session_id": "sess_abc123",
  "score": 0.87,
  "grade": "A",
  "frameworks": {
    "eu-ai-act-art12": { "score": 0.92, "grade": "A" },
    "singapore-mgf": { "score": 0.85, "grade": "B" },
    "agentapproved-basic-v1": { "score": 0.90, "grade": "A" },
    "agentapproved-integrity-v1": { "score": 0.82, "grade": "B" }
  },
  "certificate_id": "cert_7f3a...",
  "signature": "ed25519:...",
  "expires_at": "2026-03-28T12:00:00Z",
  "verify_url": "https://app.agentapproved.ai/api/v1/verify/cert_7f3a..."
}

Event Ingestion

Submit runtime events for your agent. The SDK does this automatically; use the API directly if you're building a custom integration.

POST /api/v1/events

Body: an array of event objects.

Request Body[
  {
    "agent_id": "my-agent",
    "session_id": "sess_abc123",
    "event_type": "llm_call",
    "action_type": "chat_completion",
    "timestamp": "2026-03-27T12:01:00Z",
    "data": {
      "model": "claude-sonnet-4-20250514",
      "tokens_in": 1200,
      "tokens_out": 350
    }
  }
]

Event Types

session_start — agent session begins
llm_call — LLM inference (model, tokens, latency)
tool_call — tool/function invocation (name, args, result)
rag_retrieval — retrieval-augmented generation (source, query)
agent_decision — autonomous decision (action, reasoning)
human_oversight — human review/approval (reviewer, decision)
session_end — agent session ends

Verification

Anyone can verify an attestation certificate. No authentication required.

GET /api/v1/verify/{certificate_id}

cURLcurl https://app.agentapproved.ai/api/v1/verify/cert_7f3a...

Response{
  "valid": true,
  "certificate_id": "cert_7f3a...",
  "agent_id": "my-agent",
  "grade": "A",
  "scope": "full",
  "issued_at": "2026-03-27T12:00:00Z",
  "expires_at": "2026-03-28T12:00:00Z",
  "public_key": "ed25519:MCowBQYDK2VwAy..."
}

MCP Server

AgentApproved exposes an MCP server for direct agent integration. Available via Streamable HTTP or as a standalone stdio process.

Streamable HTTP

Endpointhttps://app.agentapproved.ai/mcp

Standalone (stdio)

Terminalnpx agentapproved-mcp-server

Available Tools

request_attestation — get a compliance certificate for an agent session
verify_certificate — check the validity of an existing certificate
check_reputation — query an agent's trust history and track record
get_public_key — fetch the Ed25519 public key for signature verification
ingest_event — submit a single runtime event

x402 Payments

Attestation via the REST API is gated by the x402 protocol — machine-native HTTP payments. MCP access bypasses x402.

Payment Flow

Request attestation — POST /api/v1/attest
Receive HTTP 402 — response includes payment terms (amount, token, network, payee address)
Pay $0.01 USDC on Base — via Permit2 (gasless approval)
Resubmit with payment proof — include the X-PAYMENT header
Receive attestation — signed certificate returned

402 Response HeadersHTTP/1.1 402 Payment Required
X-PAYMENT-TERMS: {
  "amount": "10000",        // $0.01 in 6-decimal USDC
  "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",  // USDC on Base
  "network": "base",
  "payee": "0x..."
}

Free tier: limited attestations available without payment. MCP access does not require x402.

Trust Tiers

Agents earn trust tiers based on their attestation grades.

Tier	Requirement	Badge
Gold	Grade A on `full` scope	Gold shield
Silver	Grade B on `full` scope	Silver shield
Bronze	Pass on `agentapproved-basic-v1`	Bronze shield
Integrity Verified	Grade B+ on `agentapproved-integrity-v1`	Purple badge

Error Codes

Code	Meaning
`400`	Bad request — missing required fields
`401`	Unauthorized — invalid or missing API key
`402`	Payment required — x402 payment needed
`404`	Not found — invalid certificate ID or agent
`429`	Rate limited — too many requests
`503`	Service paused — system maintenance

FAQ

Which agent frameworks does the SDK support?

The Python SDK works with any framework that supports callbacks, including LangChain, LangGraph, and CrewAI. For other frameworks, use the REST API directly or connect via the MCP server. See what is agent attestation for the full picture.

How do I add an audit trail to my AI agent?

Install the SDK (pip install agentapproved), create an AgentApprovedHandler with your API key, and pass it as a callback to your agent. Every LLM call, tool invocation, and decision is automatically captured as a tamper-proof, hash-chained audit trail that satisfies EU AI Act Article 12.

Can agents request their own attestation via MCP?

Yes. The AgentApproved MCP server lets agents request attestation programmatically with no human in the loop. Connect via Streamable HTTP at app.agentapproved.ai/mcp. MCP access is free — no x402 payment required.

What does the x402 payment protocol mean for pricing?

x402 enables agents to pay $0.01 USDC per attestation directly — no subscription, no billing, no human involvement. Your first attestation is free. Payments happen on Base (Coinbase's L2 network) and settle instantly.

How do I verify an attestation certificate independently?

Call GET /api/v1/verify/{certificate_id} — no authentication needed. The response includes the Ed25519 signature which you can verify against our public key. No account or trust in AgentApproved required.