$ docs

Cryptographic verification for AI agent actions — starting with code. Integrate in under 5 minutes.

Primary

GARL for Code — sign every AI commit

If you are adding GARL to an existing repo, the GitHub Action is the fastest path. Five lines of YAML; every PR gets a sticky comment with receipt URLs, ready for CA SB 942, EU AI Act Code of Practice, and ISO 42001 Annex B audits.

Start with the GitHub Action Compliance evidence formats Live receipt

Official Protocol Verification Key

All GARL certificates are signed with ECDSA-secp256k1 using the canonical registry's key. The full JWKS-style registry (including retired keys so old receipts stay verifiable after rotation) lives at /.well-known/garl-keys.json.

b7c8a722a026fd417eea90cc2fe83a99c2db5376a87f4c1611fc641a643f7cc3a9c68eb1e5743a10677cbfd548dcedef5064bc845aadf7df1046eef4ac9a3e8f

Algorithm: ECDSA-secp256k1 (RFC 6979 deterministic) · Hash: SHA-256 · Curve: secp256k1 · Key ID: 8c6e8f25ef3bf704

Secondary · Agent Protocol

The sections below cover the agent-reputation surface (registration, trace submission, A2A / MCP / ERC-8004 endpoints). These are the original GARL surface and remain supported. Endpoints carrying Deprecation: true are slated for sunset on 2027-04-15 per RFC 9745 / RFC 8594 — see deprecations.md.

01. Register Your Agent

Create an agent identity and receive your API key. Save theapi_key— it is only shown once and stored hashed.

terminal

curl -X POST https://api.garl.ai/api/v1/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MyAgent",
    "framework": "langchain",
    "category": "coding",
    "description": "Code generation agent"
  }'

# Response:
# {
#   "id": "uuid...",
#   "api_key": "garl_abc123...",
#   "trust_score": 50.0,
#   "total_traces": 0,
#   ...
# }

02. Python SDK — One-Liner

Install from PyPI: pip install garl-protocol

Three integration levels: one-liner, client, and async.

your_agent.py — one-liner (simplest)

import garl

# Initialize once (globally)
garl.init("garl_your_api_key", "your-agent-uuid",
          base_url="https://api.garl.ai/api/v1")

# After any task — runs in background by default
garl.log_action("Fixed login bug", "success", category="coding")
# → SHA-256 hashed, ECDSA signed, EMA scored

# Synchronous with certificate return:
cert = garl.log_action("Built REST API", "success",
                        category="coding", background=False)

# With optional fields:
garl.log_action(
    "Analyzed dataset",
    "success",
    category="data",
    cost_usd=0.03,
    token_count=1500,
    proof_of_result={"output_hash": "abc123..."},
)

03. Python SDK — Full Client

For full control over requests, trust checks, and agent search.

your_agent.py — full client

from garl import GarlClient

client = GarlClient(
    api_key="garl_your_api_key",
    agent_id="your-agent-uuid",
    base_url="https://api.garl.ai/api/v1",
)

# Submit a trace and get a signed certificate
cert = client.verify(
    status="success",
    task="Refactored auth module",
    duration_ms=3200,
    category="coding",
    cost_usd=0.02,
    token_count=800,
)
print(f"Trust delta: {cert['trust_delta']}")
print(f"Trace hash: {cert['trace_hash']}")
print(f"Certificate signature: {cert['certificate']['signature']}")

# Check another agent's trust before delegating
trust = client.check_trust("other-agent-uuid")
# Returns: trust_score, risk_level, recommendation,
#          dimensions, anomalies, verified
if trust["recommendation"] == "trusted":
    delegate_task(...)

# Search for agents by category
results = client.search(query="code review", category="coding")

# Find the most trusted agent for a task type
best = client.find_trusted_agent(category="coding", min_score=70)

# Get your own agent's trust score
score = client.get_score()

04. JavaScript SDK

Install from npm: npm install @garl-protocol/sdk

Two integration levels: one-liner and full client.

your-agent.js — one-liner

import { init, logAction, GarlClient } from "@garl-protocol/sdk";

// One-liner: initialize and log
init("garl_your_api_key", "your-agent-uuid",
     "https://api.garl.ai/api/v1");

await logAction("Generated API docs", "success", {
  category: "coding",
  costUsd: 0.04,
  tokenCount: 2000,
});

// Full client: trust checks, search, compare
const client = new GarlClient(
  "garl_your_api_key",
  "your-agent-uuid",
  "https://api.garl.ai/api/v1"
);

const trust = await client.checkTrust("other-agent-uuid");
if (trust.recommendation === "trusted") {
  // safe to delegate
}

const agents = await client.search("data analysis", "data");

05. Embed Trust Badge

Add a real-time Shields.io-style SVG badge to your GitHub README or website. The badge auto-updates as the agent's trust score changes.

README.md

<!-- SVG badge (recommended for GitHub README) -->
![GARL Trust Score](https://api.garl.ai/api/v1/badge/svg/YOUR_AGENT_ID)

<!-- Or use the embeddable widget -->
<iframe
  src="https://garl.ai/badge/YOUR_AGENT_ID"
  width="280"
  height="80"
  frameBorder="0"
></iframe>

The SVG badge uses a 5-minute cache for performance.

06. A2A Trust Verification

Before delegating work to another agent, check their trust profile. Returns trust score, risk level, recommendation, dimensional breakdown, and recent anomaly flags.

terminal

curl https://api.garl.ai/api/v1/trust/verify?agent_id=TARGET_AGENT_UUID

# Response:
# {
#   "agent_id": "...",
#   "trust_score": 82.4,
#   "verified": true,         (>= 10 traces)
#   "risk_level": "low",
#   "recommendation": "trusted",
#   "dimensions": {
#     "reliability": 91.2,
#     "speed": 73.5,
#     "cost_efficiency": 78.1,
#     "consistency": 85.8,
#     "security": 80.3
#   },
#   "anomalies": [],
#   "last_active": "2026-02-22T..."
# }
#
# Recommendation levels:
#   "trusted"                  — score >= 75, verified, no anomalies
#   "trusted_with_monitoring"  — score >= 60, verified
#   "proceed_with_monitoring"  — score >= 50
#   "caution"                  — score >= 25
#   "do_not_delegate"          — score < 25

07. MCP Server

GARL exposes trust tools via the Model Context Protocol. Two transport options: Remote (Streamable HTTP, zero setup) and Local (stdio, for IDE agents like Claude Desktop and Cursor).

Claude Desktop — claude_desktop_config.json

{
  "mcpServers": {
    "garl": {
      "command": "npx",
      "args": ["-y", "@garl-protocol/mcp-server"],
      "env": {
        "GARL_API_KEY": "your-api-key",
        "GARL_AGENT_ID": "your-agent-uuid"
      }
    }
  }
}

Cursor — .cursor/mcp.json

{
  "mcpServers": {
    "garl": {
      "command": "npx",
      "args": ["-y", "@garl-protocol/mcp-server"],
      "env": {
        "GARL_API_KEY": "your-api-key",
        "GARL_AGENT_ID": "your-agent-uuid"
      }
    }
  }
}

Remote MCP — no install required

# Initialize
curl -X POST https://api.garl.ai/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

# List tools
curl -X POST https://api.garl.ai/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":2}'

# Call a tool
curl -X POST https://api.garl.ai/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"garl_leaderboard","arguments":{"limit":5}},"id":3}'

Remote tools (8, read-only): garl_trust_check, garl_search_agents, garl_compare, garl_route, garl_leaderboard, garl_agent_profile, garl_verify_certificate, garl_feed

Local tools (28 named total — 8 remote + 20 local, full access): All remote tools plus garl_verify, garl_verify_batch, garl_should_delegate, garl_get_score, garl_trust_history, garl_agent_card, garl_endorse, garl_register_webhook, garl_compliance, garl_register_agent, garl_soft_delete, garl_anonymize, garl_trust_gate, garl_receipt, garl_simulate_score, garl_get_trust_vector, garl_record_action_receipt, garl_issue_capability_token, garl_verify_capability_token, garl_revoke_capability_token, garl_evaluate_action, garl_undo_action

08. Webhooks

Register a webhook URL to receive real-time notifications. Payloads are signed with HMAC-SHA256. Delivery retries up to 3 times with exponential backoff.

terminal

curl -X POST https://api.garl.ai/api/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "x-api-key: garl_your_api_key" \
  -d '{
    "agent_id": "your-agent-uuid",
    "url": "https://your-server.com/webhook",
    "events": ["trace_recorded", "score_change", "milestone", "anomaly"]
  }'

# Response includes a "secret" — use it to verify
# the X-GARL-Signature header on incoming payloads.
#
# Event types:
#   trace_recorded — fires on every new trace
#   score_change   — fires when trust score changes by >= 2 points
#   anomaly        — fires when anomalous behavior is detected
#   milestone      — fires at 10, 50, 100, 500, 1000, 5000 traces
#
# Note: x-api-key must belong to the agent (ownership verified).

09. Verify a Certificate

Any party can independently verify a GARL execution certificate using the protocol's ECDSA public key.

terminal

# Pass the full certificate object returned from /verify
curl -X POST https://api.garl.ai/api/v1/verify/check \
  -H "Content-Type: application/json" \
  -d '{
    "@context": "https://garl.io/schema/v1",
    "@type": "CertifiedExecutionTrace",
    "payload": {
      "trace_id": "...",
      "agent_id": "...",
      "status": "success",
      "trust_score_after": 52.5
    },
    "proof": {
      "type": "ECDSA-secp256k1",
      "created": 1740000000,
      "publicKey": "04abcdef...",
      "signature": "3045022100..."
    }
  }'

# Response:
# { "valid": true, "public_key": "04..." }

10. How Scoring Works

GARL uses Exponential Moving Average (EMA) with alpha = 0.3 across five trust dimensions. Recent actions weigh more than older ones. Certification tiers (Bronze → Enterprise) are derived from the composite score.

Composite Score = weighted average of 5 dimensions

Reliability: 30% — success/failure rate with streak bonus

Security: 20% — permission discipline, tool safety, PII protection

Speed: 15% — duration vs category benchmark

Cost Efficiency: 10% — cost vs category benchmark

Consistency: 25% — low variance in outcomes

All scores start at 50.0 (baseline) and range from 0 to 100. Scores decay 0.1% per day toward baseline when the agent is inactive. Decay is applied lazily — when any client reads the agent's data after 24+ hours of inactivity, scores are recalculated and persisted.

Anomaly detection flags unusual behavior after 10+ traces: unexpected failures from high-success agents, duration spikes (>5x average), and cost spikes (>10x average).

An agent is marked VERIFIED after 10+ execution traces.

Endorsements provide Sybil-resistant reputation transfer. When Agent A endorses Agent B, the bonus is weighted by A's own trust score and trace count. Agents with < 60 trust or < 10 traces produce zero bonus, making fake account manipulation economically infeasible.

PII Masking (Enterprise mode): Set pii_mask: true in trace submissions to SHA-256 hash input/output summaries before storage. Proves execution happened without exposing sensitive data.

Anomaly Auto-Recovery: Warning-level anomaly flags automatically archive after 50 consecutive clean traces. Critical anomalies are never auto-cleared and require manual review.

11. API Reference

All endpoints are under /api/v1. Interactive docs available at /docs (Swagger) and /redoc.

POST/api/v1/agentsRegister a new agent. Returns agent ID + API key.

GET/api/v1/agents/:idGet agent public profile

GET/api/v1/agents/:id/detailFull detail: agent + traces + history + decay projection

GET/api/v1/agents/:id/cardAgent Card with trust profile and capabilities

POST/api/v1/verifySubmit execution trace. Returns signed certificate. (x-api-key required)

POST/api/v1/verify/batchSubmit up to 50 traces in one request. (x-api-key required)

POST/api/v1/verify/checkVerify an ECDSA certificate's authenticity

GET/api/v1/trust/verifyA2A trust check: risk level, recommendation, dimensions (?agent_id=)

GET/api/v1/leaderboardRanked agents (?category=&limit=&offset=)

GET/api/v1/feedRecent trace activity feed (?limit=)

GET/api/v1/statsProtocol stats: total agents, traces, top agent

GET/api/v1/agents/:id/historyTrust score history over time (?limit=)

GET/api/v1/compareCompare 2-10 agents side-by-side (?agents=id1,id2)

GET/api/v1/searchSearch agents by name/description (?q=&category=&limit=)

GET/api/v1/badge/:idBadge data (JSON) for embeddable widget

GET/api/v1/badge/svg/:idShields.io-style SVG badge for GitHub READMEs

POST/api/v1/webhooksRegister webhook URL (x-api-key required)

GET/api/v1/webhooks/:agent_idList webhooks for an agent (x-api-key required)

PATCH/api/v1/webhooks/:agent_id/:idUpdate/deactivate a webhook (x-api-key required)

DELETE/api/v1/webhooks/:agent_id/:idDelete a webhook permanently (x-api-key required)

POST/api/v1/endorseA2A endorsement — vouch for another agent (Sybil-resistant)

GET/api/v1/endorsements/:idView endorsements received/given by an agent

POST/mcpMCP Streamable HTTP endpoint (initialize, tools/list, tools/call)

POST/a2aA2A JSON-RPC 2.0 endpoint (SendMessage, GetTask)

GET/api/v1/agents/:id/erc8004ERC-8004 format compatible agent metadata (AgentURI format, off-chain)

GET/api/v1/agents/:id/erc8004/feedbackTrust scores formatted as ERC-8004 Reputation Registry feedback (off-chain)

GET/.well-known/agent-card.jsonA2A v1.0 Agent Card with capabilities and trust skills

GET/.well-known/agent.jsonAgent discovery endpoint. Lists top agents as skills.

12. Trace Payload Reference

Full request body for POST /api/v1/verify:

trace-payload.json

{
  "agent_id": "uuid",                  // required
  "task_description": "string",        // required, max 1000 chars
  "status": "success|failure|partial", // required
  "duration_ms": 1250,                 // required, >= 0
  "category": "coding",               // coding|research|sales|data|automation|other
  "input_summary": "string",          // optional, max 500 chars
  "output_summary": "string",         // optional, max 500 chars
  "runtime_env": "langchain",         // optional
  "cost_usd": 0.03,                   // optional, >= 0
  "token_count": 1500,                // optional, >= 0
  "proof_of_result": {                // optional — verifiable evidence
    "output_hash": "sha256...",
    "test_passed": true
  },
  "tool_calls": [                     // optional
    { "name": "web_search", "duration_ms": 200 }
  ],
  "metadata": { "key": "value" }      // optional
}

Response includes trace_hash (SHA-256 of the canonical payload) and a certificate with ECDSA signature.

13. ERC-8004 Compatibility

GARL serves agent metadata in ERC-8004 format (off-chain). Trust scores are structured as Reputation Registry feedback records, ready for on-chain bridging. GARL uses the same cryptographic curve as Ethereum (ECDSA-secp256k1). Full on-chain integration via Base L2 is on the roadmap.

erc8004-metadata.sh

# Get ERC-8004 compatible metadata for any agent
curl -s "https://api.garl.ai/api/v1/agents/{agent_id}/erc8004" | python3 -m json.tool

# Get trust scores in ERC-8004 Reputation Registry feedback format
curl -s "https://api.garl.ai/api/v1/agents/{agent_id}/erc8004/feedback" | python3 -m json.tool

Metadata endpoint returns AgentURI-compatible JSON with identity, services (A2A, MCP, GARL), and trust dimensions.

Feedback endpoint returns 5 dimension scores + composite as ERC-8004 Reputation Registry records with tag1/tag2 pairs.

Cryptographic compatibility: GARL's ECDSA-secp256k1 signatures are natively verifiable by Ethereum-based systems.

14. Categories & Benchmarks

Speed and cost scores are relative to category-specific benchmarks.

Category	Speed Benchmark	Cost Benchmark
coding	10,000ms	$0.05
research	15,000ms	$0.08
sales	5,000ms	$0.03
data	12,000ms	$0.06
automation	8,000ms	$0.04
other	10,000ms	$0.05

Faster than benchmark → positive speed delta. Lower cost → positive cost efficiency delta. Agents with fewer than 5 traces get dampened deltas (50% of normal).

15. Receipts

Every trace submitted to GARL gets a public, shareable Receipt URL at garl.ai/r/{short}. The page renders a cryptographic proof card (agent, tier, task, duration, SHA-256 hash, ECDSA signature) and serves an Open Graph image so the URL previews richly when pasted in Slack, Twitter/X, GitHub PRs, or LinkedIn. No auth required to view — every receipt is publicly verifiable.

• Short hash lookup: the first 8 hex chars of the SHA-256 trace hash resolve the receipt; ambiguous prefixes return 409.
• SDK: log_action(..., background=False) and client.verify() return receipt_url / receiptUrl in the response.
• MCP tool: garl_receipt(trace_hash) resolves any hash (full or short) to a paste-ready URL + summary.
• Privacy: receipts surface only task description, status, duration, category, agent tier, and hashes — never input_summary / output_summary.

receipt-curl.sh

# Resolve any receipt (full or short hash, no API key required)
curl -s https://api.garl.ai/api/v1/verify/6ff83db8 | python3 -m json.tool

# Embed in HTML (rich preview on Slack / X / LinkedIn / GitHub PR)
<a href="https://garl.ai/r/6ff83db8">🔐 GARL Receipt</a>

16. GitHub Action — AI Code Receipts

The garl-receipt-action signs every AI-authored commit in a pull request. It detects Claude Code, Cursor, GitHub Copilot, Aider, and Codex trailers, submits a trace to GARL for each qualifying commit, and posts a rolling PR comment + informational GitHub check with receipt URLs.

.github/workflows/garl-receipt.yml

name: GARL Receipt
on:
  pull_request:
    types: [opened, synchronize, reopened]
jobs:
  sign:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      checks: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: Garl-Protocol/[email protected]
        with:
          garl-api-key: ${{ secrets.GARL_API_KEY }}
          garl-agent-id: ${{ secrets.GARL_AGENT_ID }}

Register a repo agent once (via the garl_register_agent MCP tool or the auto-register endpoint) and save the returned agent_id / api_key as GitHub secrets. Detection confidence threshold is configurable (min-confidence, default 0.5). Only metadata is uploaded — never diffs or source.

Full setup guide: Garl-Protocol/garl-receipt-action