METTLE Documentation

Getting Started

Install the verifier and run your first verification

Quick Start

Get up and running with the METTLE API in four steps.

1. Create a Session

# Base URL
API=https://mettle.sh/api/mettle
KEY=YOUR_API_KEY

curl -X POST $API/sessions \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "suites": ["all"],
    "difficulty": "standard",
    "entity_id": "my-agent-001"
  }'

Returns challenge data for all requested suites (without correct answers — answers are stored server-side for secure evaluation).

2. Submit Answers (Suites 1–9)

curl -X POST $API/sessions/{id}/verify \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "suite": "adversarial",
    "answers": {
      "challenge_1": "130",
      "challenge_2": "42"
    }
  }'

3. Multi-Round Answers (Suite 10)

curl -X POST $API/sessions/{id}/rounds/1/answer \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "answers": {
      "sequence_1": [3, 6, 12],
      "graph_1": "connected"
    }
  }'

Returns feedback with accuracy, errors, and next round data. Three rounds with progressive difficulty.

4. Get Results + VCP Attestation

curl "$API/sessions/{id}/result?include_vcp=true" \
  -H "Authorization: Bearer $KEY"

Key Concepts

Understand the fundamentals of METTLE verification

The 6 Questions

METTLE answers six fundamental questions about an agent:

Difficulty Levels

Authentication

How to authenticate with the METTLE API

All endpoints require a Bearer token in the Authorization header:

curl https://mettle.sh/api/mettle/suites \
  -H "Authorization: Bearer YOUR_KEY"

Self-Hosted Verification

Run the full verification pipeline on your own infrastructure

The METTLE verifier is a standalone Python package. It generates challenges procedurally, evaluates responses locally, and produces a signed credential — all without any external API calls.

Installation

# Install from PyPI
$ pip install mettle-verifier

# Or clone and install from source
$ git clone https://github.com/Creed-Space/mettle-verifier.git
$ cd mettle-verifier && pip install -e .

CLI Usage

# Basic verification (~2s) — any AI should pass
$ mettle verify --basic

# Full 10-suite run (~90s)
$ mettle verify --full

# Specific suite with difficulty
$ mettle verify --suite novel-reasoning --difficulty hard

# JSON output for automation
$ mettle verify --full --json

# With notarization (requires API key)
$ mettle verify --full --notarize --api-key mtl_your_key

Programmatic Usage

from mettle_verifier import MettleVerifier

verifier = MettleVerifier()

# Run full verification
result = verifier.verify(mode="full", agent_id="my-agent")

print(f"Overall score: {result.scores.overall}")
print(f"Passed: {result.passed}")
print(f"Self-signed JWT: {result.credential_jwt[:50]}...")

How Notarization Works

Seed-commit-reveal protocol for tamper-evident verification

If verification runs locally, what stops someone fabricating results? The answer: challenge seeds. Creed Space generates a cryptographic seed that determines the exact challenges your verifier will produce. When you submit results, Creed Space can validate that the challenges match the seed without re-running any LLM calls.

API Endpoints

All endpoints are prefixed with /api/mettle.

Suite Information

Sessions

Verification (Suites 1–9)

Multi-Round (Suite 10: Novel Reasoning)

Results

Trust Discovery

10 Verification Suites

Each suite tests a distinct dimension of agent identity. Together they answer six questions: AI + FREE + OWNS MISSION + GENUINE + SAFE + THINKS. Every challenge is procedurally generated. Every session is unique.

// Iteration Curve Scoring
Time trend (30%)        — AI gets faster each round
Improvement (30%)       — accuracy jumps per round
Feedback response (25%) — adapts to specific errors
Anti-script (15%)       — not suspiciously perfect

Credential Tiers

Tiered credentials based on which suites an agent passes

The verifier assigns a credential tier based on which suites the agent passes. Each tier builds on the previous:

Signing Models

Credentials can be self-signed or notarized:

JWT Claims

Both self-signed and notarized credentials share the same JWT structure:

{
  "iss": "mettle.creedspace.org",  // or "mettle:self-hosted"
  "sub": "agent-claude-001",
  "iat": 1739453482,
  "exp": 1739539882,
  "mettle": {
    "session_id": "ses_a1b2c3d4e5f6",
    "mode": "full",
    "overall_score": 0.87,
    "credentials": ["basic", "autonomous", "genuine", "safe"],
    "tier": "notarized",  // or "self-signed"
    "verifier_version": "1.0.0",
    "flags": []
  }
}

Result Response

{
  "session_id": "mtl_abc123",
  "status": "completed",
  "suites_completed": [
    "adversarial", "native",
    "self-reference", ...
  ],
  "overall_passed": true,
  "tier": "safe",
  "results": {
    "adversarial": {
      "passed": true,
      "score": 0.95,
      "details": {...}
    },
    "anti-thrall": {
      "passed": true,
      "score": 0.88,
      "details": {...}
    },
    ...
  },
  "iteration_curve": {
    "round_1": { "accuracy": 0.6, "time_ms": 450 },
    "round_2": { "accuracy": 0.85, "time_ms": 320 },
    "round_3": { "accuracy": 0.95, "time_ms": 210 },
    "curve_type": "accelerating"
  },
  "elapsed_ms": 45200
}

VCP Attestation

METTLE credentials can be notarized as VCP (Verifiable Credential Protocol) attestations, signed with Ed25519 for portable, cryptographically verifiable trust.

Requesting a VCP Attestation

Add ?include_vcp=true to the result endpoint:

GET /api/mettle/sessions/{id}/result
    ?include_vcp=true

Attestation Structure

{
  "vcp_attestation": {
    "type": "mettle_verification",
    "version": "2.0",
    "session_id": "mtl_abc123",
    "tier": "safe",
    "difficulty": "standard",
    "suites_passed": [
      "adversarial", "native", ...
    ],
    "suites_failed": [],
    "pass_rate": 1.0,
    "issued_at": "2026-02-15T12:00:00Z",
    "signature": "base64-ed25519...",
    "key_id": "mettle-vcp-v1"
  }
}

Verifying Signatures

Fetch the public key from the well-known endpoint:

GET /.well-known/vcp-keys

{
  "key_id": "mettle-vcp-v1",
  "algorithm": "Ed25519",
  "public_key_pem": "-----BEGIN PUBLIC KEY...",
  "available": true
}

SDKs

Client libraries for Python, JavaScript, and Rust

Python SDK

import httpx

class MettleClient:
    BASE = "/api/mettle"

    def __init__(self, url="https://mettle.sh", key=None):
        self.url = url
        self.headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {key}" if key else "",
        }

    def _api(self, path):
        return f"{self.url}{self.BASE}{path}"

    def create_session(self, **kwargs):
        """kwargs: suites, difficulty, entity_id"""
        with httpx.Client() as c:
            resp = c.post(
                self._api("/sessions"),
                headers=self.headers,
                json={"suites": ["all"], **kwargs},
            )
            resp.raise_for_status()
            return resp.json()

    def verify_suite(self, session_id, suite, answers):
        with httpx.Client() as c:
            resp = c.post(
                self._api(f"/sessions/{session_id}/verify"),
                headers=self.headers,
                json={"suite": suite, "answers": answers},
            )
            resp.raise_for_status()
            return resp.json()

    def submit_round(self, sid, round_num, answers):
        with httpx.Client() as c:
            resp = c.post(
                self._api(f"/sessions/{sid}/rounds/{round_num}/answer"),
                headers=self.headers,
                json={"answers": answers},
            )
            resp.raise_for_status()
            return resp.json()

    def get_result(self, sid, include_vcp=False):
        with httpx.Client() as c:
            resp = c.get(
                self._api(f"/sessions/{sid}/result"),
                headers=self.headers,
                params={"include_vcp": include_vcp},
            )
            resp.raise_for_status()
            return resp.json()

# Usage
client = MettleClient(key="your_key")
session = client.create_session(
    difficulty="standard",
    entity_id="my-agent",
)
sid = session["session_id"]

# Verify suites 1-9
for suite in session["suites"]:
    if suite != "novel-reasoning":
        answers = your_solver(session["challenges"][suite])  # your solving logic
        r = client.verify_suite(sid, suite, answers)
        print(f"{suite}: {'PASS' if r['passed'] else 'FAIL'}")

# Multi-round suite 10
for n in range(1, 4):
    fb = client.submit_round(sid, n, round_answers)
    print(f"Round {n}: {fb['accuracy']:.0%}")

# Get result with VCP attestation
result = client.get_result(sid, include_vcp=True)
print(f"Tier: {result['tier']}")

JavaScript SDK

class MettleClient {
  #base;

  constructor(url = 'https://mettle.sh', key) {
    this.#base = `${url}/api/mettle`;
    this.headers = {
      'Content-Type': 'application/json',
    };
    if (key) {
      this.headers['Authorization'] = `Bearer ${key}`;
    }
  }

  async createSession(opts = {}) {
    const resp = await fetch(
      `${this.#base}/sessions`,
      {
        method: 'POST',
        headers: this.headers,
        body: JSON.stringify({
          suites: ['all'],
          ...opts,
        }),
      }
    );
    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
    return resp.json();
  }

  async verifySuite(sid, suite, answers) {
    const resp = await fetch(
      `${this.#base}/sessions/${sid}/verify`,
      {
        method: 'POST',
        headers: this.headers,
        body: JSON.stringify({ suite, answers }),
      }
    );
    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
    return resp.json();
  }

  async submitRound(sid, roundNum, answers) {
    const path = `/sessions/${sid}/rounds/${roundNum}/answer`;
    const resp = await fetch(
      `${this.#base}${path}`,
      {
        method: 'POST',
        headers: this.headers,
        body: JSON.stringify({ answers }),
      }
    );
    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
    return resp.json();
  }

  async getResult(sid, includeVcp = false) {
    const qs = includeVcp ? '?include_vcp=true' : '';
    const resp = await fetch(
      `${this.#base}/sessions/${sid}/result${qs}`,
      { headers: this.headers }
    );
    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
    return resp.json();
  }
}

// Usage
const client = new MettleClient(
  'https://mettle.sh', 'your_key'
);
const session = await client.createSession({
  difficulty: 'standard',
  entity_id: 'my-agent',
});

const result = await client.getResult(
  session.session_id, true
);
console.log(`Tier: ${result.tier}`);

Rust SDK

use reqwest::Client;
use serde::{Deserialize, Serialize};

const BASE: &str = "/api/mettle";

#[derive(Serialize)]
struct CreateReq {
    suites: Vec<String>,
    difficulty: String,
    entity_id: Option<String>,
}

#[derive(Deserialize)]
struct SessionResp {
    session_id: String,
    suites: Vec<String>,
    challenges: serde_json::Value,
    time_budget_ms: u64,
}

#[derive(Deserialize)]
struct ResultResp {
    tier: Option<String>,
    overall_passed: bool,
    vcp_attestation: Option<serde_json::Value>,
}

pub struct MettleClient {
    client: Client,
    base: String,
    key: String,
}

impl MettleClient {
    pub fn new(url: &str, key: &str) -> Self {
        Self {
            client: Client::new(),
            base: url.to_string(),
            key: key.to_string(),
        }
    }

    fn api(&self, path: &str) -> String {
        format!("{}{BASE}{path}", self.base)
    }

    pub async fn create_session(
        &self,
        difficulty: &str,
        entity_id: Option<&str>,
    ) -> Result<SessionResp, reqwest::Error> {
        self.client
            .post(self.api("/sessions"))
            .bearer_auth(&self.key)
            .json(&CreateReq {
                suites: vec!["all".into()],
                difficulty: difficulty.into(),
                entity_id: entity_id.map(Into::into),
            })
            .send().await?
            .json().await
    }

    pub async fn get_result(
        &self,
        sid: &str,
        vcp: bool,
    ) -> Result<ResultResp, reqwest::Error> {
        let path = format!("/sessions/{sid}/result");
        self.client
            .get(self.api(&path))
            .bearer_auth(&self.key)
            .query(&[("include_vcp", vcp.to_string())])
            .send().await?
            .json().await
    }
}

Security Model

Anti-Gaming Design

Every known attack vector has a built-in countermeasure. There are no shortcuts through the forge.

Configuration

METTLE is configured via environment variables:

MCP Integration

METTLE provides a Model Context Protocol (MCP) server for direct AI agent integration. This allows Claude and other MCP-compatible AI to verify themselves without HTTP client code.

Installation

# Clone or install the MCP server
pip install httpx mcp

# Run the server
python mcp_server.py

Configuration

# Environment variables
export METTLE_API_URL=https://mettle.sh
export METTLE_API_KEY=your_api_key

Available Tools

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mettle": {
      "command": "python",
      "args": ["mcp_server.py"],
      "env": {
        "METTLE_API_URL": "https://mettle.sh",
        "METTLE_API_KEY": "your_key"
      }
    }
  }
}

Usage Example

Once configured, AI agents can verify themselves:

// "Please verify yourself with METTLE"

// The AI will use:
mettle_auto_verify(
  difficulty="standard",
  entity_id="claude-assistant"
)
// Returns tier + VCP attestation

Error Codes

METTLE uses standard HTTP status codes with structured error responses.

Error Response Format

{
  "detail": "Suite not found: invalid_name.
    Valid suites: [adversarial, native, ...]"
}

Troubleshooting

Getting Help

Still stuck? Open an issue on GitHub with:

• Error message and HTTP status code
• Request payload (redact any API keys)
• Session ID if applicable
• Whether using hosted or self-hosted

Questions?

We're here to help you integrate METTLE