Developer Docs

SDK & API Reference

Everything you need to integrate AgentApproved into 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 MGF	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