⚓️ Truth Anchor Agent

Truth Anchor Agent is an MCP (Model Context Protocol) server for citation attestation. Before an agent cites a source, it can verify that the URL resolves, record the final destination, capture lightweight page metadata, and return a content hash of what was fetched.

The Problem: AI agents often cite dead, redirected, or changed URLs without checking what the source looked like at the time of use. The Solution: A paid verification step that records source availability and lightweight attestation metadata before the agent relies on a citation.

What It Guarantees

• The URL was fetched at verification time.

• The service reports the final URL, HTTP status, redirect behavior, and basic HTML metadata.

• The response includes a content_sha256 hash so downstream systems can anchor what was observed.

• Optional claim matching is a simple substring check.

What It Does Not Guarantee

• It is not a semantic fact-checking engine.

• It does not prove a page is trustworthy, only what the service observed when it fetched it.

• It does not replace search, RAG, or human review for complex claims.

🛠 Model Context Protocol (MCP) Integration

This server exposes a verify_url tool that any MCP-compliant LLM (Claude Desktop, ChatGPT, IDEs) can use autonomously.

Registration in Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "truth-anchor": {
      "command": "npx",
      "args": ["-y", "truth-anchor-agent"],
      "env": {
        "MY_WALLET_ADDRESS": "0x367B9193D4F9cb4877Ca58E6F3ce944d761d8009"
      }
    }
  }
}

Interfaces

MCP tool

The MCP tool uses a two-step flow:

1. Call verify_url with a URL.

2. Receive payment instructions if no payment proof is provided.

3. Retry with tx_hash after sending the payment.

HTTP API

The HTTP API uses an API key plus x402-style signed payments:

1. POST /auth/provision to get a free API key.

2. Use the first 50 requests for free.

3. After that, attach X-Payment to POST /verify.

💳 The Payment Flow

The HTTP API implements a 402 Payment Required flow for paid requests after the free tier is exhausted.

1. Request: Agent calls /verify with a URL.

2. Challenge: Server returns 402 Payment Required with payment instructions.

3. Payment: Agent signs a Base USDC payment authorization.

4. Verification: Agent retries with the X-Payment header.

5. Attestation: Server verifies the payment and returns the source check.

⚡️ API Reference

POST /verify

Verifies that a source resolves and returns attestation metadata. Requires:

• Authorization: Bearer <api_key>

• X-Payment after the free tier is exhausted

Headers:

Request Body:

{
  "url": "https://base.org",
  "claim": "Base is an Ethereum L2"
}

Success Response (200 OK):

{
  "url": "https://base.org",
  "final_url": "https://base.org/",
  "is_live": true,
  "status_code": 200,
  "redirected": false,
  "ssl_valid": true,
  "checked_at": "2026-04-02T12:00:00Z",
  "content_type": "text/html",
  "content_length_bytes": 31245,
  "title": "Base",
  "description": "Base is a secure, low-cost, builder-friendly Ethereum L2.",
  "content_sha256": "9d72c4...",
  "claim": "Base is an Ethereum L2",
  "claim_found": true,
  "claim_match_method": "substring",
  "paid": false,
  "free_requests_remaining": 49
}

🏗 Tech Stack

• FastAPI — High-performance Python API framework.

• Web3.py — Real-time on-chain verification (Base RPC).

• SQLite — Replay attack prevention and transaction indexing.

• Fly.io — Global edge deployment.

• Base — L2 Ethereum for fast, low-cost USDC payments.

Positioning Notes

• Primary wedge: citation attestation for agents

• Rejected for now: broad truth layer, general fact-checking, and multi-tool expansion

• Product gap and validation notes live in docs/product-positioning.md, docs/user-validation.md, and docs/user-validation-proxy.md

🛠 Local Development

# 1. Clone and Install
git clone https://github.com/cristiano-c1/truth-anchor-agent
cd truth-anchor-agent
pip install -r requirements.txt

# 2. Configure
echo "MY_WALLET_ADDRESS=0x367B9193D4F9cb4877Ca58E6F3ce944d761d8009" > .env

# 3. Run
uvicorn main:app --reload

📜 License

Distributed under the MIT License. See LICENSE for more information.