verify_receipt_by_hash

Verify consent receipt validity using its cryptographic hash to confirm authorization before processing requests. Returns verification results and receipt details.

Instructions

Verify a receipt by its canonical hash. Public — no API key needed. Use this to check if an agent has a valid consent receipt before serving a request. Returns receipt details and cryptographic verification result.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`canonical_hash`	Yes	The canonical hash of the receipt to verify

Implementation Reference

app.py:525-550 (handler)

The actual core logic function for verifying the receipt.

def verify_receipt_by_hash(canonical_hash):
    """Public endpoint: verify a receipt by its canonical hash. No auth required.
    This is the endpoint providers' SDKs call to verify an agent's receipt."""
    receipt = db.get_receipt_by_hash(canonical_hash)
    if not receipt:
        return error_response('RECEIPT_NOT_FOUND', 'No receipt found with this hash', 404)

    # Verify the cryptographic signature
    km = get_key_manager()
    service = ReceiptService(km)

    # Build minimal receipt dict for verification
    verify_result = service.verify_receipt(receipt)

    # Return public-safe receipt data (strip workspace_id for privacy)
    return jsonify({
        'valid': verify_result.get('valid', False),
        'receipt_id': receipt['receipt_id'],
        'canonical_hash': receipt['canonical_hash'],
        'agent_id': receipt['agent_id'],
        'action_type': receipt['action_type'],
        'terms_url': receipt['terms_url'],
        'terms_hash': receipt['terms_hash'],
        'amount_charged': receipt['amount_charged'],
        'timestamp': receipt['timestamp'],
        'signature': receipt['signature'],

openterms_mcp_server.py:120-134 (registration)

Registration of the tool in the MCP server.

{
    "name": "verify_receipt_by_hash",
    "description": (
        "Verify a receipt by its canonical hash. Public — no API key needed. "
        "Use this to check if an agent has a valid consent receipt before serving a request. "
        "Returns receipt details and cryptographic verification result."
    ),
    "inputSchema": {
        "type": "object",
        "required": ["canonical_hash"],
        "properties": {
            "canonical_hash": {"type": "string", "description": "The canonical hash of the receipt to verify"},
        },
    },
},

openterms_mcp_server.py:368-375 (handler)

The MCP server handler that dispatches the request to the underlying API endpoint.

elif name == "verify_receipt_by_hash":
    canonical_hash = arguments["canonical_hash"]
    resp = client.get(f"/v1/receipts/verify/{canonical_hash}", headers=_headers(auth=False))
    if resp.status_code == 200:
        data = resp.json()
        valid = data.get("valid", False)
        status = "✅ VALID" if valid else "❌ INVALID"
        verification = data.get("verification", {})

Openterms-mcp